MoDI

Começar

Introdução

A MoDI Open API (versão 1.3) permite a instituições integrar serviços de identidade digital: leitura de documentos (OCR), comparação facial, prova de vida, sessões de verificação KYC completas, envio de SMS e verificação de números móveis junto das operadoras (Subscriber Check).

Todas as respostas, incluindo erros, seguem o mesmo envelope JSON. As operações estão organizadas por serviço e cada uma exige a chave da respectiva subscrição.

Os dados de todas as requisições, incluindo os testes online, são armazenados permanentemente na base de dados do MoDI.

Perfis

PerfilAcesso
INSTITUTIONCatálogo, subscrição e activação de serviços e todos os endpoints operacionais. É o perfil documentado nesta página.
ADMIN_BACKOFFICEEquipa MoDI: revê, aprova e rejeita manifestações de interesse. Sem acesso aos serviços operacionais.

Início rápido

O percurso de integração tem sete passos:

PassoAcçãoOperação
1Submeter manifestação de interessePOST /institutions/interest
2Obter aprovação (credenciais enviadas por e-mail)GET /institutions/interest/{requestId}
3Iniciar sessão (OTP por e-mail)POST /auth/login + POST /auth/login/verify-otp
4Alterar a senha temporáriaPOST /auth/password
5Subscrever um serviçoPOST /subscriptions
6Activar a chave de SandboxPOST /subscriptions/{subscriptionId}/activate-key
7Consumir o serviçoEndpoint operacional com X-API-Key
Manifestação de interesse
  → Aprovação
  → Login
  → Alterar senha temporária
  → Subscrever serviço
  → Activar chave SANDBOX
  → Consumir o serviço

Ambientes

AmbienteURL baseFinalidade
Auth (conta, serviços, subscrições, SMS)https://gateway.app.tablu.tech/api/authLogin, catálogo, subscrições, chaves, saldo e SMS
KYC e No-Codehttps://gateway.app.tablu.tech/api/kycOCR, biometria, sessões de verificação e blocos No-Code

Regras

O ambiente (SANDBOX ou PRODUCTION) é definido pela chave, não pelo URL: as chaves são activadas separadamente por ambiente e uma subscrição pode ter uma chave SANDBOX e uma chave PRODUCTION.

A activação em SANDBOX gera automaticamente o MOU informativo associado. PRODUCTION requer homologação prévia.

Pendente no contrato: O procedimento de homologação para produção não está descrito no contrato.

Exemplo

Pendente: O procedimento de homologação para produção não está descrito no contrato.

Iniciar sessão

POST/auth/login

Primeiro passo do login: valida e-mail e password e envia um código OTP para o e-mail registado. Não devolve tokens: devolve um challengeId para usar em POST /auth/login/verify-otp.

Requisitos

  • Sem autenticação
  • Content-Type: application/json ou multipart/form-data

Corpo (application/json)

CampoTipoObrigatórioDescrição
emailstringObrigatório—
passwordstringObrigatório—

Regras

O OTP expira ao fim de expiresInSeconds (300 segundos).

Enquanto mustChangePassword for true, apenas POST /auth/password fica acessível; os restantes endpoints devolvem 403 PASSWORD_CHANGE_REQUIRED.

curl -X POST "https://gateway.app.tablu.tech/api/auth/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"<password>"}'

Confirmar OTP

POST/auth/login/verify-otp

Segundo passo do login: valida o código OTP recebido por e-mail e devolve o accessToken (15 minutos) e o refreshToken (7 dias).

Requisitos

  • Sem autenticação
  • Content-Type: application/json ou multipart/form-data

Corpo (application/json)

CampoTipoObrigatórioDescrição
challengeIdstringObrigatórioDevolvido por POST /auth/login
otpstringObrigatórioCódigo recebido por e-mail

Regras

Para renovar os tokens sem novo OTP use POST /auth/refresh com o refreshToken; cada refreshToken só pode ser usado uma vez.

curl -X POST "https://gateway.app.tablu.tech/api/auth/auth/login/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{"challengeId":"ch_3kq8ZxV0bL2mN7pR4tYw1A","otp":"<código>"}'

Alterar password

POST/auth/password

Obrigatório no primeiro login com password temporária. A password temporária é de uso único.

Requisitos

  • Authorization: Bearer <accessToken>

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>

Corpo (application/json)

CampoTipoObrigatórioDescrição
currentPasswordstringObrigatórioPassword actual ou temporária
newPasswordstringObrigatórioRequisitos internacionais de complexidade

Regras

mustChangePassword fica true até o primeiro POST /auth/password ser concluído.

curl -X POST "https://gateway.app.tablu.tech/api/auth/auth/password" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"<temporária>","newPassword":"<nova>"}'

Headers

HeaderUso
AuthorizationBearer <accessToken>. Endpoints de conta no Auth: subscrições, chaves, saldo e password.
X-API-KeyChave da subscrição do serviço. Única credencial dos endpoints KYC, No-Code e SMS (não levam Authorization).
Content-Typeapplication/json ou multipart/form-data (envio de ficheiros).
# Auth
-H "Authorization: Bearer <accessToken>"

# KYC, No-Code e SMS
-H "X-API-Key: ky_sbx_exemplo"

Formato das respostas

Todas as respostas seguem o mesmo envelope, incluindo os erros.

CampoTipoSignificado
successbooleanSucesso técnico do pedido.
statusnumberCódigo HTTP da resposta.
messagestringMensagem descritiva.
dataobject | nullResultado da operação; null em caso de erro.
transactionIdstringIdentificador da transacção.
amountstringValor associado à transacção.
errorsarray | nullLista de erros; null em caso de sucesso.

Regras

success indica que o pedido foi processado; não indica o resultado da verificação. Esse resultado está em data (por exemplo data.result ou data.passed).

Os valores de amount nos exemplos são ilustrativos e não representam preços comerciais.

{
  "success": true,
  "status": 200,
  "message": "Operation completed successfully.",
  "data": {},
  "transactionId": "TRX-EXEMPLO",
  "amount": "0.00",
  "errors": null
}

Tratamento de erros

Em erro: success: false, data: null e errors preenchido com code, field e detail.

Distinguir resultados

SituaçãoComo se identifica
Sucesso técnicosuccess: true, HTTP 2xx
Resultado da verificaçãoHTTP 200 com data.result / data.passed (pode ser negativo)
Erro de validaçãoHTTP 400 ou 422, errors com o campo
Falha de autenticaçãoHTTP 401 (token) ou 403 (scope, serviço, password)
IndisponibilidadeHTTP 503; a sessão permanece em PROCESSING

Códigos HTTP

HTTPQuando ocorre
400Requisição malformada
401Token ausente, inválido ou expirado
402Saldo insuficiente (INSUFFICIENT_BALANCE)
403Scope insuficiente ou serviço não contratado
404Recurso inexistente
409Conflito com o estado actual do recurso
422Falha de validação de negócio
429Rate limit excedido (Retry-After)
500Erro interno; pode repetir o pedido
503Provedor externo indisponível; sessão permanece em PROCESSING

Códigos de negócio

CódigoDescrição
INVALID_FILE_FORMATFicheiro fora dos formatos aceites (JPG, JPEG, PNG, PDF)
FILE_TOO_LARGEFicheiro excede 5 MB
DOCUMENT_UNREADABLEQualidade insuficiente para OCR
DOCUMENT_EXPIREDDocumento com validade ultrapassada
FACE_NOT_DETECTEDNenhuma face detectada na selfie
FACE_MISMATCHSimilaridade abaixo do limiar contratado
LIVENESS_FAILEDProva de vida detectou possível fraude
DUPLICATE_IDENTITY_FOUNDA face corresponde a uma identidade já existente
UNDERAGE_APPLICANTProponente abaixo da idade mínima configurada
PHONE_INVALIDNúmero de telefone inválido ou não E.164
SESSION_EXPIREDSessão de verificação expirada
INSUFFICIENT_BALANCESaldo pré-pago insuficiente para a operação
SERVICE_NOT_ENABLEDServiço não incluído no plano contratado
PASSWORD_CHANGE_REQUIREDPassword temporária ainda não foi alterada
SUBSCRIBER_DATA_REQUIREDContact-verify sem nome, n.º do documento ou data de nascimento válidos (422)
SELFIE_REQUIREDBio-verify sem selfie (422)
DOCUMENT_REQUIREDBio-verify sem frente do documento (422)
SUBSCRIBER_NOT_FOUNDNúmero sem registo na operadora (422)
SUBSCRIBER_BIOMETRY_NOT_FOUNDTitular sem fotografia de registo na operadora (422)
SUBSCRIBER_INVALID_DATADados recusados pela operadora; detalhe por campo em errors (400/413)
SUBSCRIBER_LEVEL_NOT_ALLOWEDA operadora não tem acordo para o nível pedido nem para um nível abaixo (403)
SUBSCRIBER_RATE_LIMITEDLimite de pedidos da operadora excedido (429)
SUBSCRIBER_CHECK_UNAVAILABLEServiço da operadora indisponível ou sem configuração (503)
{
  "success": false,
  "status": 422,
  "message": "O ficheiro excede o tamanho máximo permitido.",
  "data": null,
  "transactionId": "TRX-20260709-000160",
  "amount": "0.00",
  "errors": [
    {
      "code": "FILE_TOO_LARGE",
      "field": null,
      "detail": "O ficheiro excede o tamanho máximo permitido."
    }
  ]
}

Acesso e configuração

Submeter manifestação de interesse

POST/institutions/interest

Cria o registo com estado PENDING na fila de revisão da MoDI. Após aprovação, a instituição recebe por e-mail as credenciais; em caso de rejeição, recebe o motivo.

Requisitos

  • Sem autenticação
  • multipart/form-data

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
companyNamestringObrigatórioNome legal da instituição
addressstringObrigatório—
emailstringObrigatórioTorna-se o login da instituição, após aprovação
phoneNumberstringObrigatórioFormato E.164
websiteUrlstringOpcional—
taxIdfileObrigatórioNUIT (documento anexo)
licenseDocumentfileObrigatórioAlvará
commercialCertificatefileObrigatórioCertidão Comercial
curl -X POST "https://gateway.app.tablu.tech/api/auth/institutions/interest" \
  -F "companyName=Banco Exemplo, S.A." \
  -F "address=Av. Exemplo, 100, Maputo" \
  -F "[email protected]" \
  -F "phoneNumber=+258840000000" \
  -F "taxId=@./nuit.pdf" \
  -F "licenseDocument=@./alvara.pdf" \
  -F "commercialCertificate=@./certidao.pdf"

Consultar estado da manifestação

GET/institutions/interest/{requestId}

Consulta pública por requestId. Estados: PENDING, APPROVED, REJECTED. Quando REJECTED, reason indica o motivo.

Requisitos

  • Sem autenticação

Caminho

CampoTipoObrigatórioDescrição
requestIdstringObrigatórioIdentificador devolvido na submissão (REQ-…)
curl -X GET "https://gateway.app.tablu.tech/api/auth/institutions/interest/REQ-01J9ZP001A"

Listar serviços disponíveis

GET/services

Devolve os serviços que a instituição pode subscrever, identificados por serviceCode.

Requisitos

  • Perfil INSTITUTION
  • Authorization

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>
curl -X GET "https://gateway.app.tablu.tech/api/auth/services" \
  -H "Authorization: Bearer <accessToken>"

Subscrever serviço

POST/subscriptions

Regista o pedido de uso do serviço. Em SANDBOX a subscrição fica ACTIVE de imediato; em PRODUCTION fica PENDING até aprovação do Backoffice MoDI. Ainda não gera apiKey: active a chave a seguir.

Requisitos

  • Perfil INSTITUTION
  • Authorization

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>

Corpo (application/json)

CampoTipoObrigatórioDescrição
serviceCodeenumObrigatórioVERIFICATION_SESSION, DOCUMENT_INTELLIGENCE, FACE_VERIFICATION, SMS, LIVENESS, SUBSCRIBER_CHECK
environmentenumOpcionalSANDBOX (por omissão) ou PRODUCTION
labelstringOpcionalNome interno da subscrição
sourceenumOpcionalAPI (por omissão), BACKOFFICE ou NO_CODE_BUILDER
correlationIdstringOpcionalIdentificador do pedido no seu sistema; repetir o mesmo devolve a subscrição já criada (resultCode ALREADY_ACTIVE)
curl -X POST "https://gateway.app.tablu.tech/api/auth/subscriptions" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"serviceCode":"FACE_VERIFICATION","environment":"SANDBOX","label":"Onboarding"}'

Activar chave do serviço

POST/subscriptions/{subscriptionId}/activate-key

Gera a apiKey para o ambiente indicado. SANDBOX e PRODUCTION são activadas separadamente.

Requisitos

  • Perfil INSTITUTION
  • Authorization
  • PRODUCTION requer homologação prévia

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>

Caminho

CampoTipoObrigatórioDescrição
subscriptionIdstringObrigatórioSUB-…

Corpo (application/json)

CampoTipoObrigatórioDescrição
environmentenumObrigatórioSANDBOX ou PRODUCTION
allowedIpsarrayOpcionalIPs ou redes CIDR autorizados a usar a chave (até 50). Vazio: sem restrição

Regras

A activação em SANDBOX gera automaticamente o MOU informativo associado, sem intervenção manual.

allowedIps lista os IPs autorizados a usar a chave; vazio significa sem restrição.

curl -X POST "https://gateway.app.tablu.tech/api/auth/subscriptions/SUB-01J9ZMS8W2P9/activate-key" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"environment":"SANDBOX","allowedIps":["203.0.113.10"]}'

Listar subscrições

GET/subscriptions

Devolve as subscrições da instituição autenticada, com estado por ambiente.

Requisitos

  • Perfil INSTITUTION
  • Authorization

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>

Regras

A lista é paginada: use limit (por omissão 50) e startingAfter com o nextCursor devolvido. Pode filtrar por status.

curl -X GET "https://gateway.app.tablu.tech/api/auth/subscriptions" \
  -H "Authorization: Bearer <accessToken>"

Referência dos serviços

Analisar documento

POST/documents/analyze

Serviço isolado de leitura e extracção de dados de documentos de identificação.

Requisitos

  • Perfil INSTITUTION
  • X-API-Key da subscrição DOCUMENT_INTELLIGENCE
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição DOCUMENT_INTELLIGENCE

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
clientReferencestringObrigatórioReferência interna da instituição
documentTypeenumOpcionalNATIONAL_ID, PASSPORT, DRIVING_LICENCE, DIRE, VOTER_CARD
documentFrontfileObrigatório—
documentBackfileCondicionalObrigatório para NATIONAL_ID e DRIVING_LICENCE
returnPortraitbooleanOpcionalDevolve o retrato recortado em base64

Regras

result pode ser CLEAR, CONSIDER (indício de adulteração) ou FAILED.

portrait só é devolvido quando returnPortrait é true; caso contrário vem null.

extracted traz os campos lidos do documento (topo), e os blocos ocr (zona visual) e mrz (zona de leitura óptica) com os mesmos campos por origem. Os campos dependem do tipo de documento.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/documents/analyze" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "clientReference=PROP-2026-004417" \
  -F "documentType=NATIONAL_ID" \
  -F "documentFront=@./bi-frente.jpg" \
  -F "documentBack=@./bi-verso.jpg" \
  -F "returnPortrait=true"

Comparar rosto

POST/biometrics/face-match

Compara uma selfie com uma imagem de referência. Cada verificação é guardada na base biométrica da instituição, permitindo detectar se o proponente já existe.

Indique a referência de uma de duas formas: envie o ficheiro reference, ou indique referenceDocumentId de um documento já analisado no OCR (DOC-…).

Requisitos

  • Perfil INSTITUTION
  • X-API-Key da subscrição FACE_VERIFICATION
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição FACE_VERIFICATION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
clientReferencestringObrigatórioReferência interna da instituição
selfiefileObrigatório—
referencefileCondicionalImagem de referência
referenceDocumentIdstringCondicionalAlternativa: ID de um documento já analisado (DOC-…)
checkExistingbooleanOpcionalSe true, pesquisa 1:N na base da instituição. Por omissão true

Regras

similarity é devolvido numa escala de 0 a 1 (por exemplo 0.984).

Quando existingIdentity é true, subscriberId identifica o registo já existente e o clientReference da submissão original fica disponível na consulta da verificação.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/biometrics/face-match" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "clientReference=PROP-2026-004417" \
  -F "selfie=@./selfie.jpg" \
  -F "referenceDocumentId=DOC-01J9ZKQ83WPX"

Consultar verificação facial

GET/biometrics/face-match/{checkId}

Devolve o resultado guardado de uma verificação facial anterior.

Requisitos

  • X-API-Key da subscrição FACE_VERIFICATION

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição FACE_VERIFICATION

Caminho

CampoTipoObrigatórioDescrição
checkIdstringObrigatórioCHK-…

Regras

A consulta não é facturada (amount 0.00).

curl -X GET "https://gateway.app.tablu.tech/api/kyc/biometrics/face-match/CHK-01J9ZKZM55RD" \
  -H "X-API-Key: ky_sbx_exemplo"

Prova de vida isolada

POST/biometrics/liveness

Prova de vida sobre uma selfie, sem comparação com documento. Indicada para reautenticação de clientes já registados ou como passo prévio a outra verificação.

Requisitos

  • Perfil INSTITUTION
  • X-API-Key da subscrição FACE_VERIFICATION
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição FACE_VERIFICATION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
clientReferencestringObrigatórioReferência interna da instituição
selfiefileObrigatórioImagem do rosto (JPG, JPEG ou PNG)

Regras

liveness.result: CLEAR ou FAILED. checked: false quando não foi possível avaliar a imagem (conta como FAILED, com o motivo em message).

Sem rosto na imagem: FACE_NOT_DETECTED.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/biometrics/liveness" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "clientReference=PROP-2026-004417" \
  -F "selfie=@./selfie.jpg"

Criar sessão

POST/verifications

Fluxo KYC orquestrado: documento, face, prova de vida e telefone, com decisão consolidada. Recomendado para onboarding de clientes finais.

A criação devolve 202: o pedido foi aceite e é processado posteriormente. Consulte o resultado com GET /verifications/{sessionId}.

Requisitos

  • Perfil INSTITUTION
  • X-API-Key da subscrição VERIFICATION_SESSION
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
clientReferencestringObrigatórioÚnica por sessão
firstNamestringObrigatório—
lastNamestringObrigatório—
dateOfBirthdateObrigatórioYYYY-MM-DD
phoneNumberstringCondicionalObrigatório se o check PHONE estiver activo
documentTypeenumObrigatórioNATIONAL_ID, PASSPORT, DRIVING_LICENCE, DIRE, VOTER_CARD
documentFrontfileObrigatório—
documentBackfileCondicionalObrigatório para NATIONAL_ID e DRIVING_LICENCE
selfiefileObrigatório—
checksarrayOpcionalDOCUMENT, FACE_MATCH, LIVENESS, PHONE. Por omissão, todas
checkExistingbooleanOpcionalPesquisa 1:N na base da instituição. Por omissão true
curl -X POST "https://gateway.app.tablu.tech/api/kyc/verifications" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "clientReference=PROP-2026-004417" \
  -F "firstName=Amélia José" \
  -F "lastName=Cossa" \
  -F "dateOfBirth=1992-03-14" \
  -F "phoneNumber=+258840000000" \
  -F "documentType=NATIONAL_ID" \
  -F "documentFront=@./bi-frente.jpg" \
  -F "documentBack=@./bi-verso.jpg" \
  -F "selfie=@./selfie.jpg"

Consultar sessão

GET/verifications/{sessionId}

Devolve o estado, a decisão consolidada e o resultado de cada check.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Caminho

CampoTipoObrigatórioDescrição
sessionIdstringObrigatórioVER-…

Regras

Estados de sessão: AWAITING_INPUT, PROCESSING, APPROVED, DECLINED, REVIEW, EXPIRED.

Resultado de cada check: CLEAR, CONSIDER ou FAILED.

curl -X GET "https://gateway.app.tablu.tech/api/kyc/verifications/VER-01J9ZK7Q4T8MHV" \
  -H "X-API-Key: ky_sbx_exemplo"

Listar sessões

GET/verifications

Lista paginada. A resposta contém data.items e data.hasMore.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Query

CampoTipoObrigatórioDescrição
limitnumberOpcionalNúmero de itens por página (ex.: 20)
startingAfterstringOpcionalCursor: sessionId a partir do qual continuar
sessionStatusenumOpcionalFiltro por estado
clientReferencestringOpcionalFiltro por referência
createdFromdateOpcionalFiltro por data de criação
createdTodateOpcionalFiltro por data de criação

Regras

Cada item tem o mesmo formato da consulta de sessão. Para a página seguinte, envie startingAfter com o valor de nextCursor.

limit por omissão: 20.

curl -X GET "https://gateway.app.tablu.tech/api/kyc/verifications?limit=20&startingAfter=VER-01J9ZK7Q4T8MHV" \
  -H "X-API-Key: ky_sbx_exemplo"

Enviar SMS

POST/sms/send

Envia mensagens SMS ao proponente ou cliente final. Este serviço apenas envia: não valida códigos OTP.

Requisitos

  • Perfil INSTITUTION
  • X-API-Key da subscrição SMS

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição SMS

Corpo (application/json)

CampoTipoObrigatórioDescrição
messagesarrayObrigatórioLista de { phoneNumber, message }
messages[].phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
messages[].messagestringObrigatórioTexto da mensagem
transactionCodestringOpcionalReferência do envio no seu sistema
senderstringOpcionalRemetente; por omissão o configurado na conta
asyncstringOpcionalEnvio assíncrono; por omissão o configurado na conta

Regras

data é a resposta do gateway SMS: data.data.transaction identifica o envio; success e failure listam o resultado por número.

curl -X POST "https://gateway.app.tablu.tech/api/auth/sms/send" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -H "Content-Type: application/json" \
  -d '{"transactionCode":"PROP-2026-004417","messages":[{"phoneNumber":"+258840000000","message":"Mensagem de exemplo"}]}'

Regras comuns

Verificação da titularidade e do risco do número móvel junto da operadora (Vodacom, Movitel, Tmcel). São cinco blocos do No-Code; cada um pode ser usado num fluxo ou chamado isoladamente em POST /no-code/subscriber-check/{block}.

Normalização: o número é normalizado para 258…; são aceites 84…, 0…, +258… e 258…. Tem de ter um prefixo móvel de 82 a 87; caso contrário, 422 PHONE_INVALID.

Decisão negativa: um bloco concluído devolve HTTP 200 com data.passed e data.reasonCode. passed: false é um resultado negativo, não um erro técnico (message: «Bloco recusado.»).

data.config mostra as opções efectivamente aplicadas; data.payload é o resumo gravado na execução (número mascarado, sem dados pessoais); data.response é a resposta devolvida pela operadora.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Motivos de decisão (reasonCode)

CódigoDescrição
SUBSCRIBER_HIGH_RISKNúmero classificado como de alto risco pela operadora
SUBSCRIBER_SERVICE_INACTIVEServiço do número diferente do estado exigido
SUBSCRIBER_OWNERSHIP_UNCERTAINTitularidade incerta e acceptUncertain não activo
SUBSCRIBER_OWNERSHIP_REJECTEDOs dados não correspondem ao titular
OTP_RISK_CAUTIONRisco moderado e acceptCaution = false
OTP_RISK_HIGHRisco elevado para envio de OTP
OTP_RISK_REJECTEDEnvio de OTP desaconselhado pela operadora
RISK_SCORE_TOO_HIGHlevel acima de maxLevel
RISK_SCORE_BLOCKEDaction = BLOCK
BIO_PARTIAL_MATCHCorrespondência parcial e acceptPartial não activo
BIO_POSSIBLE_DUPLICATEPossível duplicado na base da operadora
BIO_REJECTEDA biometria não corresponde ao titular
841234567     → 258841234567
0841234567    → 258841234567
+258841234567 → 258841234567
258841234567  → 258841234567

Prefixos móveis aceites: 82 a 87

Titular do número

POST/no-code/subscriber-check/NUMBER_OWNER

Confirma que o número está registado e activo na operadora e avalia a titularidade.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
fullNamestringOpcionalNome do cliente, comparado com o titular
documentNumberstringOpcionalN.º do documento, comparado com o do titular
configstring (JSON)OpcionalOpções do bloco, por exemplo {"acceptUncertain":false,"requireActive":true}. Campos omitidos usam os valores por omissão

Regras

result: OWNERSHIP_CONFIRMED, OWNERSHIP_UNCERTAIN, OWNERSHIP_REJECTED ou HIGH_RISK.

HIGH_RISK falha sempre, mesmo com acceptUncertain.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/no-code/subscriber-check/NUMBER_OWNER" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "phoneNumber=841234567" \
  -F "fullName=Amélia José Cossa" \
  -F 'config={"requireActive":true}'

Titularidade do contacto

POST/no-code/subscriber-check/CONTACT_OWNERSHIP

Compara os dados do cliente com o registo do titular na operadora.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
fullNamestringObrigatórioNome completo do cliente
documentNumberstringObrigatórioN.º do documento de identificação
dateOfBirthdateObrigatórioYYYY-MM-DD
configstring (JSON)OpcionalOpções do bloco, por exemplo {"acceptUncertain":false,"serviceState":"ACTIVE"}. Campos omitidos usam os valores por omissão

Regras

Sem nome, documento ou data de nascimento válidos devolve 422 SUBSCRIBER_DATA_REQUIRED, com os campos em falta em errors.

Erros aplicáveis

SUBSCRIBER_DATA_REQUIRED

curl -X POST "https://gateway.app.tablu.tech/api/kyc/no-code/subscriber-check/CONTACT_OWNERSHIP" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "phoneNumber=861234521" \
  -F "fullName=Nome Apelido" \
  -F "documentNumber=000000000000A" \
  -F "dateOfBirth=1990-01-01"

Risco para OTP

POST/no-code/subscriber-check/OTP_RISK

Avalia se é seguro enviar um código OTP para o número (por exemplo, após troca recente de SIM).

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
configstring (JSON)OpcionalOpções do bloco, por exemplo {"checkLevel":"P2","acceptCaution":true,"fallbackLevel":true}. Campos omitidos usam os valores por omissão

Regras

result: SAFE, SAFE_WITH_CAUTION ou risco elevado / rejeitado.

appliedLevel indica o nível efectivamente usado após o fallback; a Movitel só disponibiliza P1.

Sem nível disponível devolve 403 SUBSCRIBER_LEVEL_NOT_ALLOWED.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/no-code/subscriber-check/OTP_RISK" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "phoneNumber=861234521" \
  -F 'config={"checkLevel":"P2"}'

Score de risco

POST/no-code/subscriber-check/RISK_SCORE

Devolve o nível de risco do número para o contexto de uso indicado.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
configstring (JSON)OpcionalOpções do bloco, por exemplo {"maxLevel":"MEDIUM","dataLevel":"P2","context":"KYC","fallbackLevel":true}. Campos omitidos usam os valores por omissão

Regras

Passa quando level é igual ou inferior a maxLevel e action é diferente de BLOCK.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/no-code/subscriber-check/RISK_SCORE" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "phoneNumber=821234545" \
  -F 'config={"maxLevel":"MEDIUM","context":"KYC"}'

Biometria na operadora

POST/no-code/subscriber-check/BIO_VERIFY

Compara a selfie e o documento com a fotografia de registo do titular na operadora.

Requisitos

  • X-API-Key da subscrição VERIFICATION_SESSION
  • Bloco do No-Code (o mesmo passo usado nos fluxos)
  • multipart/form-data

Headers

CampoTipoObrigatórioDescrição
X-API-KeystringObrigatórioChave activa da subscrição VERIFICATION_SESSION

Corpo (multipart/form-data)

CampoTipoObrigatórioDescrição
phoneNumberstringObrigatórioNúmero móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87
faceImagefileObrigatórioSelfie do cliente
documentImagefileObrigatórioFrente do documento de identificação
configstring (JSON)OpcionalOpções do bloco, por exemplo {"acceptPartial":false}. Campos omitidos usam os valores por omissão

Regras

result: VERIFIED, PARTIAL_MATCH, possível duplicado ou rejeitado.

Titular sem fotografia de registo na operadora devolve 422 SUBSCRIBER_BIOMETRY_NOT_FOUND.

curl -X POST "https://gateway.app.tablu.tech/api/kyc/no-code/subscriber-check/BIO_VERIFY" \
  -H "X-API-Key: ky_sbx_exemplo" \
  -F "phoneNumber=841234567" \
  -F "faceImage=@./selfie.jpg" \
  -F "documentImage=@./bi-frente.jpg"

Conta

Consultar saldo

GET/account/balance

Devolve o plano, o modo de facturação e o saldo disponível da instituição.

Requisitos

  • Perfil INSTITUTION
  • Authorization

Headers

CampoTipoObrigatórioDescrição
AuthorizationstringObrigatórioBearer <accessToken>
curl -X GET "https://gateway.app.tablu.tech/api/auth/account/balance" \
  -H "Authorization: Bearer <accessToken>"

Solicitar acesso

Prefere falar connosco antes de submeter a manifestação de interesse? Deixe os seus dados.