Documentacao publica

Integracao simples para validar identidade.

Este guia cobre apenas as rotas necessarias para empresas testarem, enviar verificacoes e consultar resultados. A ideia e permitir que equipas liguem a API aos seus sistemas sem depender de processos manuais para confirmar BI, selfie e resultado.

Ambientes

Frontend: https://ocr.orioncodetech.com
API: https://api.ocr.orioncodetech.com
Docs local: http://localhost:3000/docs
API local: http://localhost:8020

02. Secao

Autenticacao

Tokens

As rotas de verificacao usam Bearer token. O token sandbox e retornado uma unica vez ao criar o ambiente de teste. Tokens de producao sao emitidos depois da validacao comercial e operacional.

Authorization: Bearer $KYC_TOKEN

Ambiente de teste

O token de teste permite chamar as rotas de verificacao com limite diario de 100 requests por empresa. Use este ambiente para validar a integracao antes de pedir credenciais de producao.

03. Secao

Rotas publicas para integracao.

Use estas rotas para criar token sandbox, solicitar acesso de producao, enviar imagens e consultar resultados.

POST/v1/public/test-token

Gerar token sandbox

Sem autenticacao

Cria ou reutiliza uma empresa de teste pelo NUIT e email tecnico, gera um token sandbox e retorna o token completo apenas nesta resposta.

company_namestring

Nome curto da empresa.

legal_namestring opcional

Nome legal/comercial completo.

nuitstring

NUIT da empresa.

contact_emailemail

Email tecnico para contacto.

contact_phonestring opcional

Contacto telefonico.

Request

curl -X POST https://api.ocr.orioncodetech.com/v1/public/test-token \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Empresa Demo",
    "legal_name": "Empresa Demo Lda",
    "nuit": "123456789",
    "contact_email": "tecnico@empresa.co.mz",
    "contact_phone": "+258840000000"
  }'

Response 201

{
  "company": {
    "id": "cmp_662e16f6a49d428684978932c5fcf85f",
    "name": "Empresa Demo",
    "environment": "test"
  },
  "token": "kyc_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_id": "tok_...",
  "token_prefix": "kyc_test_xxxxxxxx",
  "scopes": ["kyc:verify", "kyc:read"],
  "daily_request_limit": 100,
  "docs_url": "/docs",
  "message": "Token de teste criado. Use Authorization: Bearer <token> nas rotas KYC."
}

POST/v1/public/production-token-requests

Solicitar token de producao

Sem autenticacao

Regista um pedido de acesso live. A equipa valida os dados da empresa, caso de uso, enquadramento legal e contacto tecnico antes de emitir credenciais de producao.

company_namestring

Nome curto da empresa.

legal_namestring opcional

Nome legal/comercial completo.

nuitstring

NUIT da empresa.

contact_emailemail

Email tecnico.

contact_phonestring

Contacto obrigatorio.

use_casestring opcional

Exemplo: onboarding digital, validacao de utilizadores, cadastro interno.

Request

curl -X POST https://api.ocr.orioncodetech.com/v1/public/production-token-requests \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Empresa Demo",
    "legal_name": "Empresa Demo Lda",
    "nuit": "123456789",
    "contact_email": "tecnico@empresa.co.mz",
    "contact_phone": "+258840000000",
    "use_case": "Onboarding digital de clientes"
  }'

Response 202

{
  "request_id": "evt_...",
  "status": "received",
  "message": "Pedido recebido. A equipa ira validar os dados e contactar a empresa."
}

GET/v1/me

Validar token e empresa

Bearer token

Confirma que o token esta ativo e devolve a empresa associada. Use esta rota no setup inicial da integracao.

Request

curl -X GET https://api.ocr.orioncodetech.com/v1/me \
  -H "Authorization: Bearer $KYC_TOKEN"

Response 200

{
  "company": {
    "id": "cmp_...",
    "name": "Empresa Demo",
    "nuit": "123456789",
    "status": "active",
    "environment": "test"
  },
  "token": {
    "id": "tok_...",
    "token_prefix": "kyc_test_xxxxxxxx",
    "scopes": ["kyc:verify", "kyc:read"],
    "status": "active"
  }
}

POST/v1/kyc/verifications

Criar verificacao KYC

Bearer token com kyc:verify

Envia a frente do BI, verso do BI e selfie do cliente. A resposta inclui a decisao, dados documentais encontrados, resultado facial, checks executados e identificador da verificacao.

external_referenceform string opcional

ID interno do cliente no sistema da empresa.

document_frontfile obrigatorio

Imagem da frente do BI. JPEG, PNG ou WEBP.

document_backfile obrigatorio

Imagem do verso do BI. JPEG, PNG ou WEBP.

selfiefile obrigatorio

Foto do rosto do cliente. Deve conter apenas uma pessoa.

Request multipart/form-data

curl -X POST https://api.ocr.orioncodetech.com/v1/kyc/verifications \
  -H "Authorization: Bearer $KYC_TOKEN" \
  -F "external_reference=client-123" \
  -F "document_front=@bi-front.jpg;type=image/jpeg" \
  -F "document_back=@bi-back.jpg;type=image/jpeg" \
  -F "selfie=@selfie.jpg;type=image/jpeg"

Response 201

{
  "verification_id": "ver_a3863ed8238f4c81b1ea28f07c0b1fbc",
  "company_id": "cmp_662e16f6a49d428684978932c5fcf85f",
  "external_reference": "client-123",
  "status": "completed",
  "decision": "pending_review",
  "risk_score": 0.5,
  "document": {
    "type": "bi",
    "document_number": "010107091480B",
    "full_name": "CLIENTE EXEMPLO",
    "date_of_birth": "1990-01-01",
    "expiry_date": "2030-01-01",
    "ocr_confidence": 0.82,
    "field_confidences": {}
  },
  "face": {
    "document_face_detected": true,
    "selfie_face_detected": true,
    "selfie_face_count": 1,
    "face_match_score": 0.78,
    "liveness_score": 0.86,
    "is_match": true,
    "is_live": true
  },
  "checks": [
    {
      "name": "document_front_received",
      "status": "passed"
    }
  ],
  "model_versions": {
    "decision_engine": "rules_v0"
  },
  "message": "Verificacao pendente de revisao manual.",
  "created_at": "2026-05-12T23:35:43.692181",
  "completed_at": "2026-05-12T23:35:43.698162"
}

GET/v1/kyc/verifications/{verification_id}

Consultar verificacao

Bearer token com kyc:read

Devolve o mesmo contrato da criacao da verificacao. Use para reconstruir estado, validar uma referencia depois de uma falha de rede ou apresentar resultado em dashboards internos.

Request

curl -X GET https://api.ocr.orioncodetech.com/v1/kyc/verifications/ver_a3863ed8238f4c81b1ea28f07c0b1fbc \
  -H "Authorization: Bearer $KYC_TOKEN"

GET/v1/kyc/verifications/{verification_id}/report

Relatorio com auditoria

Bearer token com kyc:read

Inclui o resultado da verificacao e a lista de eventos de auditoria relacionados ao processamento.

Request

curl -X GET https://api.ocr.orioncodetech.com/v1/kyc/verifications/ver_a3863ed8238f4c81b1ea28f07c0b1fbc/report \
  -H "Authorization: Bearer $KYC_TOKEN"

Campo adicional

{
  "audit_events": [
    {
      "id": "evt_...",
      "event_type": "verification.completed",
      "payload": {},
      "created_at": "2026-05-12T23:35:43.698162"
    }
  ]
}

04. Secao

Resultados

Decisoes

approvedAprovado

Documento, selfie e regras passaram dentro dos limites configurados.

rejectedRejeitado

A verificacao falhou em checks importantes.

pending_reviewRevisao manual

Dados insuficientes, baixa qualidade ou sinais inconclusivos.

Status dos checks

passedPassou

O check foi concluido com sucesso.

failedFalhou

O check falhou e pode afetar a decisao.

reviewRevisao

O check exige analise manual ou informacao adicional.

skippedIgnorado

O check nao foi executado naquele contexto.

05. Secao

Erros

A API usa codigos HTTP padrao. O campo principal de erro edetail.

400Imagem invalida

Formato nao suportado, imagem corrompida ou ficheiro maior que o limite.

401Token ausente ou invalido

Envie Authorization: Bearer $KYC_TOKEN.

403Acesso negado

Empresa inativa ou token sem scope necessario.

404Nao encontrado

verification_id inexistente para a empresa autenticada.

422Payload invalido

Campos obrigatorios ausentes ou com formato incorreto.

429Quota excedida

Ambiente sandbox passou o limite diario de verificacoes.

500Erro interno

Falha inesperada. Repetir com mesma external_reference ajuda a rastrear.

Exemplo

{
  "detail": "Daily sandbox request limit reached. Limit: 100 verifications per day."
}