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
| Perfil | Acesso |
|---|---|
| INSTITUTION | Catálogo, subscrição e activação de serviços e todos os endpoints operacionais. É o perfil documentado nesta página. |
| ADMIN_BACKOFFICE | Equipa 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:
| Passo | Acção | Operação |
|---|---|---|
| 1 | Submeter manifestação de interesse | POST /institutions/interest |
| 2 | Obter aprovação (credenciais enviadas por e-mail) | GET /institutions/interest/{requestId} |
| 3 | Iniciar sessão (OTP por e-mail) | POST /auth/login + POST /auth/login/verify-otp |
| 4 | Alterar a senha temporária | POST /auth/password |
| 5 | Subscrever um serviço | POST /subscriptions |
| 6 | Activar a chave de Sandbox | POST /subscriptions/{subscriptionId}/activate-key |
| 7 | Consumir o serviço | Endpoint 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çoAmbientes
| Ambiente | URL base | Finalidade |
|---|---|---|
| Auth (conta, serviços, subscrições, SMS) | https://gateway.app.tablu.tech/api/auth | Login, catálogo, subscrições, chaves, saldo e SMS |
| KYC e No-Code | https://gateway.app.tablu.tech/api/kyc | OCR, 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.
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)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| string | Obrigatório | — | |
| password | string | Obrigató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)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| challengeId | string | Obrigatório | Devolvido por POST /auth/login |
| otp | string | Obrigatório | Có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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <accessToken> |
Corpo (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| currentPassword | string | Obrigatório | Password actual ou temporária |
| newPassword | string | Obrigatório | Requisitos 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
| Header | Uso |
|---|---|
| Authorization | Bearer <accessToken>. Endpoints de conta no Auth: subscrições, chaves, saldo e password. |
| X-API-Key | Chave da subscrição do serviço. Única credencial dos endpoints KYC, No-Code e SMS (não levam Authorization). |
| Content-Type | application/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.
| Campo | Tipo | Significado |
|---|---|---|
| success | boolean | Sucesso técnico do pedido. |
| status | number | Código HTTP da resposta. |
| message | string | Mensagem descritiva. |
| data | object | null | Resultado da operação; null em caso de erro. |
| transactionId | string | Identificador da transacção. |
| amount | string | Valor associado à transacção. |
| errors | array | null | Lista 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ção | Como se identifica |
|---|---|
| Sucesso técnico | success: true, HTTP 2xx |
| Resultado da verificação | HTTP 200 com data.result / data.passed (pode ser negativo) |
| Erro de validação | HTTP 400 ou 422, errors com o campo |
| Falha de autenticação | HTTP 401 (token) ou 403 (scope, serviço, password) |
| Indisponibilidade | HTTP 503; a sessão permanece em PROCESSING |
Códigos HTTP
| HTTP | Quando ocorre |
|---|---|
| 400 | Requisição malformada |
| 401 | Token ausente, inválido ou expirado |
| 402 | Saldo insuficiente (INSUFFICIENT_BALANCE) |
| 403 | Scope insuficiente ou serviço não contratado |
| 404 | Recurso inexistente |
| 409 | Conflito com o estado actual do recurso |
| 422 | Falha de validação de negócio |
| 429 | Rate limit excedido (Retry-After) |
| 500 | Erro interno; pode repetir o pedido |
| 503 | Provedor externo indisponível; sessão permanece em PROCESSING |
Códigos de negócio
| Código | Descrição |
|---|---|
| INVALID_FILE_FORMAT | Ficheiro fora dos formatos aceites (JPG, JPEG, PNG, PDF) |
| FILE_TOO_LARGE | Ficheiro excede 5 MB |
| DOCUMENT_UNREADABLE | Qualidade insuficiente para OCR |
| DOCUMENT_EXPIRED | Documento com validade ultrapassada |
| FACE_NOT_DETECTED | Nenhuma face detectada na selfie |
| FACE_MISMATCH | Similaridade abaixo do limiar contratado |
| LIVENESS_FAILED | Prova de vida detectou possível fraude |
| DUPLICATE_IDENTITY_FOUND | A face corresponde a uma identidade já existente |
| UNDERAGE_APPLICANT | Proponente abaixo da idade mínima configurada |
| PHONE_INVALID | Número de telefone inválido ou não E.164 |
| SESSION_EXPIRED | Sessão de verificação expirada |
| INSUFFICIENT_BALANCE | Saldo pré-pago insuficiente para a operação |
| SERVICE_NOT_ENABLED | Serviço não incluído no plano contratado |
| PASSWORD_CHANGE_REQUIRED | Password temporária ainda não foi alterada |
| SUBSCRIBER_DATA_REQUIRED | Contact-verify sem nome, n.º do documento ou data de nascimento válidos (422) |
| SELFIE_REQUIRED | Bio-verify sem selfie (422) |
| DOCUMENT_REQUIRED | Bio-verify sem frente do documento (422) |
| SUBSCRIBER_NOT_FOUND | Número sem registo na operadora (422) |
| SUBSCRIBER_BIOMETRY_NOT_FOUND | Titular sem fotografia de registo na operadora (422) |
| SUBSCRIBER_INVALID_DATA | Dados recusados pela operadora; detalhe por campo em errors (400/413) |
| SUBSCRIBER_LEVEL_NOT_ALLOWED | A operadora não tem acordo para o nível pedido nem para um nível abaixo (403) |
| SUBSCRIBER_RATE_LIMITED | Limite de pedidos da operadora excedido (429) |
| SUBSCRIBER_CHECK_UNAVAILABLE | Serviç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)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| companyName | string | Obrigatório | Nome legal da instituição |
| address | string | Obrigatório | — |
| string | Obrigatório | Torna-se o login da instituição, após aprovação | |
| phoneNumber | string | Obrigatório | Formato E.164 |
| websiteUrl | string | Opcional | — |
| taxId | file | Obrigatório | NUIT (documento anexo) |
| licenseDocument | file | Obrigatório | Alvará |
| commercialCertificate | file | Obrigatório | Certidã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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| requestId | string | Obrigatório | Identificador 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <accessToken> |
Corpo (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| serviceCode | enum | Obrigatório | VERIFICATION_SESSION, DOCUMENT_INTELLIGENCE, FACE_VERIFICATION, SMS, LIVENESS, SUBSCRIBER_CHECK |
| environment | enum | Opcional | SANDBOX (por omissão) ou PRODUCTION |
| label | string | Opcional | Nome interno da subscrição |
| source | enum | Opcional | API (por omissão), BACKOFFICE ou NO_CODE_BUILDER |
| correlationId | string | Opcional | Identificador 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <accessToken> |
Caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| subscriptionId | string | Obrigatório | SUB-… |
Corpo (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| environment | enum | Obrigatório | SANDBOX ou PRODUCTION |
| allowedIps | array | Opcional | IPs 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição DOCUMENT_INTELLIGENCE |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| clientReference | string | Obrigatório | Referência interna da instituição |
| documentType | enum | Opcional | NATIONAL_ID, PASSPORT, DRIVING_LICENCE, DIRE, VOTER_CARD |
| documentFront | file | Obrigatório | — |
| documentBack | file | Condicional | Obrigatório para NATIONAL_ID e DRIVING_LICENCE |
| returnPortrait | boolean | Opcional | Devolve 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição FACE_VERIFICATION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| clientReference | string | Obrigatório | Referência interna da instituição |
| selfie | file | Obrigatório | — |
| reference | file | Condicional | Imagem de referência |
| referenceDocumentId | string | Condicional | Alternativa: ID de um documento já analisado (DOC-…) |
| checkExisting | boolean | Opcional | Se 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.
Erros aplicáveis
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição FACE_VERIFICATION |
Caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| checkId | string | Obrigatório | CHK-… |
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição FACE_VERIFICATION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| clientReference | string | Obrigatório | Referência interna da instituição |
| selfie | file | Obrigatório | Imagem 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| clientReference | string | Obrigatório | Única por sessão |
| firstName | string | Obrigatório | — |
| lastName | string | Obrigatório | — |
| dateOfBirth | date | Obrigatório | YYYY-MM-DD |
| phoneNumber | string | Condicional | Obrigatório se o check PHONE estiver activo |
| documentType | enum | Obrigatório | NATIONAL_ID, PASSPORT, DRIVING_LICENCE, DIRE, VOTER_CARD |
| documentFront | file | Obrigatório | — |
| documentBack | file | Condicional | Obrigatório para NATIONAL_ID e DRIVING_LICENCE |
| selfie | file | Obrigatório | — |
| checks | array | Opcional | DOCUMENT, FACE_MATCH, LIVENESS, PHONE. Por omissão, todas |
| checkExisting | boolean | Opcional | Pesquisa 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| sessionId | string | Obrigatório | VER-… |
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Query
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| limit | number | Opcional | Número de itens por página (ex.: 20) |
| startingAfter | string | Opcional | Cursor: sessionId a partir do qual continuar |
| sessionStatus | enum | Opcional | Filtro por estado |
| clientReference | string | Opcional | Filtro por referência |
| createdFrom | date | Opcional | Filtro por data de criação |
| createdTo | date | Opcional | Filtro 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição SMS |
Corpo (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| messages | array | Obrigatório | Lista de { phoneNumber, message } |
| messages[].phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| messages[].message | string | Obrigatório | Texto da mensagem |
| transactionCode | string | Opcional | Referência do envio no seu sistema |
| sender | string | Opcional | Remetente; por omissão o configurado na conta |
| async | string | Opcional | Envio 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ódigo | Descrição |
|---|---|
| SUBSCRIBER_HIGH_RISK | Número classificado como de alto risco pela operadora |
| SUBSCRIBER_SERVICE_INACTIVE | Serviço do número diferente do estado exigido |
| SUBSCRIBER_OWNERSHIP_UNCERTAIN | Titularidade incerta e acceptUncertain não activo |
| SUBSCRIBER_OWNERSHIP_REJECTED | Os dados não correspondem ao titular |
| OTP_RISK_CAUTION | Risco moderado e acceptCaution = false |
| OTP_RISK_HIGH | Risco elevado para envio de OTP |
| OTP_RISK_REJECTED | Envio de OTP desaconselhado pela operadora |
| RISK_SCORE_TOO_HIGH | level acima de maxLevel |
| RISK_SCORE_BLOCKED | action = BLOCK |
| BIO_PARTIAL_MATCH | Correspondência parcial e acceptPartial não activo |
| BIO_POSSIBLE_DUPLICATE | Possível duplicado na base da operadora |
| BIO_REJECTED | A biometria não corresponde ao titular |
841234567 → 258841234567
0841234567 → 258841234567
+258841234567 → 258841234567
258841234567 → 258841234567
Prefixos móveis aceites: 82 a 87Titular 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| fullName | string | Opcional | Nome do cliente, comparado com o titular |
| documentNumber | string | Opcional | N.º do documento, comparado com o do titular |
| config | string (JSON) | Opcional | Opçõ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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| fullName | string | Obrigatório | Nome completo do cliente |
| documentNumber | string | Obrigatório | N.º do documento de identificação |
| dateOfBirth | date | Obrigatório | YYYY-MM-DD |
| config | string (JSON) | Opcional | Opçõ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
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| config | string (JSON) | Opcional | Opçõ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.
Erros aplicáveis
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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| config | string (JSON) | Opcional | Opçõ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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| X-API-Key | string | Obrigatório | Chave activa da subscrição VERIFICATION_SESSION |
Corpo (multipart/form-data)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phoneNumber | string | Obrigatório | Número móvel moçambicano: 84…, 0…, +258… ou 258…. Prefixo 82 a 87 |
| faceImage | file | Obrigatório | Selfie do cliente |
| documentImage | file | Obrigatório | Frente do documento de identificação |
| config | string (JSON) | Opcional | Opçõ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.
Erros aplicáveis
SELFIE_REQUIREDDOCUMENT_REQUIREDSUBSCRIBER_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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | Obrigatório | Bearer <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.
