Panamá

Serviço de validação civil para o Panamá. Realiza a Verificação de Identidade contra os dados do Registro Civil do Panamá.

Endpoint

POST /services/civilValidation

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	API Key de autorização de acesso.
family	string	Não	Valor: Onboarding. Obrigatório com o serviço de Tracking.

Todas as chamadas aos Endpoints para Tracking com Identity Platform devem conter o header family.

Validação Completa Mobile

Realiza a validação de dados e a correspondência facial contra o Registro Civil do Panamá utilizando a plataforma móvel.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
operation	string	Sim	Operação de validação a ser realizada. Valor: "FULL".
platform	string	Sim	Plataforma a partir da qual a solicitação é realizada. Valor: "MOBILE".
tokenOcr	string	Sim	Token gerado pelo Widget SelphID nativo ou híbrido, criptografado em AES256 e Tokenizado, enviado em formato Base64. Contém o resultado OCR do Documento de identidade capturado.
bestImage	string	Sim	Imagem em aberto do rosto do usuário. Necessária para operações FACIAL ou FULL.
countryCode	string	Sim	Código do país no formato ISO 3166-1 alfa-3. Valor: "PAN".
returnPII	boolean	Não	Indica se deseja receber os dados pessoais gerados pelo serviço OCR e a resposta do Registro Civil.
documentValidation	boolean	Não	Indica se deseja iniciar a validação do documento, retornando scanReference e type.
rastreamento	object	Não	Objeto que representa as informações de Tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação

{
  "operation": "FULL",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "bestImage": "base64BestImageString",
  "countryCode": "PAN",
  "returnPII": false,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Ver Código de Resultado do Serviço.
serviceTime	string	Tempo total de processamento (milissegundos).
serviceResultLog	string	Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção.
serviceTransactionId	string	Identificador da transação associado à solicitação processada pela API.
civilDataValidation	array	Array que representa as validações OCR contra os dados obtidos do Registro Civil. Sua presença depende do Registro Civil consultado.
civilDataValidation[].field	string	Nome do campo validado (ex. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Código do resultado da validação. "0": Validado corretamente. "-99": Possivelmente adulterado.
civilDataValidation[].message	string	Mensagem descritiva do resultado da validação.
serviceFacialAuthenticationResult	integer	Código que indica o resultado da coincidência facial. Ver Resultado da Autenticação Facial do Serviço.
serviceFacialSimilarityResult	number	Valor que indica a semelhança facial entre o rosto na foto do documento e a selfie do usuário. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Hash de integridade do Template Biométrico utilizado em uma autenticação facial positiva ou incerta.
serviceDocument	string	String JSON que representa o documento capturado. Suas propriedades são todos os campos extraídos pelo processo OCR.
civilServiceData	string	String JSON com os dados pessoais obtidos do Registro Civil (só é retornado se returnPII foi enviado como true na solicitação).

Exemplo de resposta

{
  "serviceResultCode": 0,
  "serviceTime": "1799",
  "serviceResultLog": "Positivo | Serviço executado com sucesso",
  "serviceTransactionId": "f0392b79-664c-476f-8fad-d30009b68d60",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possivelmente adulterado"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validado com sucesso"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validado com sucesso"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.9946,
  "serviceFacialAuthenticationHash": "NA",
  "serviceDocument": "{\"Back/INPUT/Issuer\":\"PAN\",\"Back/ML/DateOfBirth\":\"13/04/1964\",\"Back/ML/DateOfExpiry\":\"16/04/2023\",\"Back/ML/DocumentNumber\":\"1 0627 0723\",\"Back/ML/ElectoralAddress\":\"\",\"Back/ML/FatherName\":\"LUOOT NOT. HOSPITAL CENTRAL SAN JOSE\",\"Back/ML/Gender\":\"\",\"Back/ML/MotherName\":\"XO F\",\"Back/ML/PlaceOfBirth\":\"Domicilio Ectoral SAN BOSCO CENTRAL SAN JOSE\",\"DateOfBirth\":\"13/04/1964\",\"DateOfExpiry\":\"16/04/2023\",\"DocumentCaptured\":\"CR/All\",\"DocumentNumber\":\"1 0627 0723\",\"FirstName\":\"\",\"Front/INPUT/Issuer\":\"PAN\",\"Front/ML/CC\":\".:\")}",
  "civilServiceData": "{\"nombres\":\"APUY STIER\",\"fechaNacimiento\":\"13/04/1964\",\"fechaVencimiento\":\"16/04/2023\",\"lugarNacimiento\":\"SAN BOSCO CENTRAL SAN JOSE\"}"
}

Validação Completa Web

Realiza a validação de dados e a correspondência facial contra o Registro Civil do Panamá utilizando a plataforma web.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
operation	string	Sim	Operação de validação a ser realizada. Valor: "FULL".
platform	string	Sim	Plataforma a partir da qual a solicitação é realizada. Valor: "WEB".
imageFrontDocument	string	Sim	Captura frontal do documento, imagem em Base64 sem o cabeçalho de tipo MIME. Requerido para a plataforma WEB.
imageBackDocument	string	Sim	Captura traseira do documento, imagem em Base64 sem o cabeçalho de tipo MIME. Requerido para a plataforma WEB.
bestImage	string	Sim	Imagem em aberto do rosto do usuário. Necessária para operações FACIAL ou FULL.
countryCode	string	Sim	Código do país no formato ISO 3166-1 alfa-3. Valor: "PAN".
returnPII	boolean	Não	Indica se deseja receber os dados pessoais gerados pelo serviço OCR e a resposta do Registro Civil.
documentValidation	boolean	Não	Indica se deseja iniciar a validação do documento, retornando scanReference e type.
rastreamento	object	Não	Objeto que representa as informações de Tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação

{
  "operation": "FULL",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "bestImage": "base64BestImageString",
  "countryCode": "PAN",
  "returnPII": false,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Ver Código de Resultado do Serviço.
serviceTime	string	Tempo total de processamento (milissegundos).
serviceResultLog	string	Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção.
serviceTransactionId	string	Identificador da transação associado à solicitação processada pela API.
civilDataValidation	array	Array que representa as validações OCR contra os dados obtidos do Registro Civil. Sua presença depende do Registro Civil consultado.
civilDataValidation[].field	string	Nome do campo validado (ex. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Código do resultado da validação. "0": Validado corretamente. "-99": Possivelmente adulterado.
civilDataValidation[].message	string	Mensagem descritiva do resultado da validação.
serviceFacialAuthenticationResult	integer	Código que indica o resultado da coincidência facial. Ver Resultado da Autenticação Facial do Serviço.
serviceFacialSimilarityResult	number	Valor que indica a semelhança facial entre o rosto na foto do documento e a selfie do usuário. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Hash de integridade do Template Biométrico utilizado em uma autenticação facial positiva ou incerta.
serviceDocument	string	String JSON que representa o documento capturado. Suas propriedades são todos os campos extraídos pelo processo OCR.
civilServiceData	string	String JSON com os dados pessoais obtidos do Registro Civil (só é retornado se returnPII foi enviado como true na solicitação).

Exemplo de resposta

{
  "serviceResultCode": 0,
  "serviceTime": "4074",
  "serviceResultLog": "Negativo | Serviço executado com sucesso",
  "serviceTransactionId": "e1243a68-be8f-464c-94a7-e8a5562d71a0",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possivelmente adulterado"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validado com sucesso"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validado com sucesso"
    }
  ],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0,
  "serviceFacialAuthenticationHash": "NA",
  "serviceDocument": "{\"ASK4BACK\":\"NO\",\"BACKSIDE\":{\"FIELD_DATA\":{\"ADDRESS\":\"SAN RAFAEL POAS ALAJUELA\",\"BARCODES\":[{\"DATA\":\"\",\"TYPE\":\"\"}],\"BIRTH_DATE\":\" 19 10 1984\",\"BIRTH_PLACE\":\"CENTRO CENTRAL ALAJUELA\",\"EXPIRATION_DATE\":\" 07 02 2028\",\"FATHER_NAME\":\"LUIS RODRIGUEZ CASTRO\",\"IDENTITY_NUMBER\":\"205990558\",\"MOTHER_NAME\":\"FLORA ISABEL QUESADA CASTRO\",\"SEX\":\"\",\"VERTICAL_NUMBER\":\"000631975\"}},\"CHECKS\":{\"IDENTITY_NUMBER_SIDE_MATCH\":true},\"COUNTRY_CODE\":\"PAN\",\"DOC_MODEL\":\"NEW\",\"FRONTSIDE\":{\"FIELD_DATA\":{\"FIRST_SURNAME\":\"RODRIGUEZ\",\"IDENTITY_NUMBER\":\"205990558\",\"NAME\":\"LUIS\",\"SECOND_SURNAME\":\"QUESADA\"}},\"SCORING\":{\"BACK_CONFIDENCE\":0.976855586876,\"BACK_SHA256\":\"4dfb73e9c8cbba6db42d1e4938ba1e62244bfe26efecd55579a4f65c9aed63ae\",\"FIELDS_RETURNED\":15,\"FIELDS_TOTAL\":15,\"FRONT_CONFIDENCE\":0.922833224138,\"FRONT_SHA256\":\"506b3192e0e80f851012f895300c63e8c85fea0ca78b9d99195e6256afadc5d4\",\"OVERALL_RATING\":100.0,\"OVERALL_SIDE_CORRESPONDENCE\":100.0}}",
  "civilServiceData": "{\"nombres\":\"LUIS RODRIGUEZ QUESADA\",\"fechaNacimiento\":\"19/10/1984\",\"lugarNacimiento\":\"CENTRO CENTRAL ALAJUELA\",\"direccion\":\"SAN RAFAEL POAS ALAJUELA\"}"
}

Validação Facial Mobile

Realiza a correspondência facial contra as imagens oficiais do Registro Civil do Panamá utilizando a plataforma móvel. Não inclui validação de dados.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
operation	string	Sim	Operação de validação a ser realizada. Valor: "FACIAL".
platform	string	Sim	Plataforma a partir da qual a solicitação é realizada. Valor: "MOBILE".
bestImage	string	Sim	Imagem em aberto do rosto do usuário. Necessária para operações FACIAL ou FULL.
documentNumber	string	Não	Número do documento do usuário.
countryCode	string	Sim	Código do país no formato ISO 3166-1 alfa-3. Valor: "PAN".
rastreamento	object	Não	Objeto que representa as informações de Tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação

{
  "operation": "FACIAL",
  "platform": "MOBILE",
  "bestImage": "base64BestImageString",
  "documentNumber": "1 0627 0723",
  "countryCode": "PAN",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Ver Código de Resultado do Serviço.
serviceTime	string	Tempo total de processamento (milissegundos).
serviceResultLog	string	Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção.
serviceTransactionId	string	Identificador da transação associado à solicitação processada pela API.
civilDataValidation	array	Array que representa as validações OCR contra os dados obtidos do Registro Civil. Sua presença depende do Registro Civil consultado.
civilDataValidation[].field	string	Nome do campo validado (ex. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Código do resultado da validação. "0": Validado corretamente. "-99": Possivelmente adulterado.
civilDataValidation[].message	string	Mensagem descritiva do resultado da validação.
serviceFacialAuthenticationResult	integer	Código que indica o resultado da coincidência facial. Ver Resultado da Autenticação Facial do Serviço.
serviceFacialSimilarityResult	number	Valor que indica a semelhança facial entre o rosto na foto do documento e a selfie do usuário. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Hash de integridade do Template Biométrico utilizado em uma autenticação facial positiva ou incerta.

Exemplo de resposta

{
  "serviceResultCode": 0,
  "serviceTime": "2800",
  "serviceResultLog": "Serviço executado com sucesso",
  "serviceTransactionId": "24681357-2468-1357-9024-246813579024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possivelmente adulterado"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validado com sucesso"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validado com sucesso"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.94,
  "serviceFacialAuthenticationHash": "NA"
}

Validação Facial Web

Realiza a correspondência facial contra as imagens oficiais do Registro Civil do Panamá utilizando a plataforma web. Não inclui validação de dados.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
operation	string	Sim	Operação de validação a ser realizada. Valor: "FACIAL".
platform	string	Sim	Plataforma a partir da qual a solicitação é realizada. Valor: "WEB".
bestImage	string	Sim	Imagem em aberto do rosto do usuário. Necessária para operações FACIAL ou FULL.
documentNumber	string	Não	Número do documento do usuário.
countryCode	string	Sim	Código do país no formato ISO 3166-1 alfa-3. Valor: "PAN".
rastreamento	object	Não	Objeto que representa as informações de Tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação

{
  "operation": "FACIAL",
  "platform": "WEB",
  "bestImage": "base64BestImageString",
  "documentNumber": "205990558",
  "countryCode": "PAN",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Ver Código de Resultado do Serviço.
serviceTime	string	Tempo total de processamento (milissegundos).
serviceResultLog	string	Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção.
serviceTransactionId	string	Identificador da transação associado à solicitação processada pela API.
civilDataValidation	array	Array que representa as validações OCR contra os dados obtidos do Registro Civil. Sua presença depende do Registro Civil consultado.
civilDataValidation[].field	string	Nome do campo validado (ex. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Código do resultado da validação. "0": Validado corretamente. "-99": Possivelmente adulterado.
civilDataValidation[].message	string	Mensagem descritiva do resultado da validação.
serviceFacialAuthenticationResult	integer	Código que indica o resultado da coincidência facial. Ver Resultado da Autenticação Facial do Serviço.
serviceFacialSimilarityResult	number	Valor que indica a semelhança facial entre o rosto na foto do documento e a selfie do usuário. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Hash de integridade do Template Biométrico utilizado em uma autenticação facial positiva ou incerta.

Exemplo de resposta

{
  "serviceResultCode": 0,
  "serviceTime": "3200",
  "serviceResultLog": "Serviço executado com sucesso",
  "serviceTransactionId": "87654321-4321-4321-4321-210987654321",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possivelmente adulterado"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validado com sucesso"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validado com sucesso"
    }
  ],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.15,
  "serviceFacialAuthenticationHash": "NA"
}

Tabelas de referência

Código de Resultado do Serviço

O serviceResultCode indica o resultado geral da execução do serviço:

serviceResultCode	Descrição	Código HTTP
0	A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente.	200

Resultado da Autenticação Facial do Serviço

O serviceFacialAuthenticationResult indica o resultado das operações de coincidência facial (somente para operações FULL e FACIAL):

Código	Resultado	Descrição
0	NONE	Não foi possível realizar a verificação facial.
1	NEGATIVE	O processo foi executado corretamente. A comparação do padrão facial dos rostos não corresponde.
3	POSITIVE	O processo foi executado corretamente. A comparação do padrão facial dos rostos é positiva. O valor de serviceFacialSimilarityResult indica a % de semelhança entre as imagens comparadas.
4	NENHUM DEVIDO A EXCESSO DE POSE	Não foi possível realizar a verificação facial devido à posição do rosto.
5	NENHUM DEVIDO A EXTRAÇÕES INVÁLIDAS	Não foi possível realizar a verificação facial devido a problemas na extração do padrão facial.

Erros comuns

400 Requisição inválida

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Não autorizado

{
  "message": "Unauthorized"
}

403 Acesso negado

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Gateway inválido

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Tempo limite do gateway

{
  "message": "Endpoint request timed out"
}