Remetente

O Remetente é o participante que inicia e paga por uma transação. Todo remetente deve passar pela triagem de KYC (Know Your Customer), e seus limites de transação são determinados pelo seu nível de conformidade.

Configuração Inicial de Conformidade

No início da sua integração, a equipe de conformidade da Inyo trabalha com a sua organização para definir um framework de conformidade personalizado, adequado ao seu produto e ao perfil dos seus clientes. Esse framework determina:

• Níveis de conformidade — níveis que definem quanto um cliente pode enviar em janelas de tempo definidas (24h, 30d, 180d)
• Regras de validação — os dados e documentos exigidos para cada nível (ex.: nome, SSN, comprovante de renda)
• Controles de risco — limiares que disparam due diligence reforçada

Essa configuração é única por tenant e impacta diretamente como os participantes são verificados e quais operações eles podem realizar.

Criando um Remetente (v2 — Recomendado)

Endpoint: POST /organizations/{tenant}/v2/people
Autenticação: Nível de tenant (x-api-key)

⚠️ O endpoint v1 POST /organizations/{tenant}/people está obsoleto. Use o v2 — ele aceita o mesmo payload e adiciona validação e verificação de documentos integradas à solução KYC.

O endpoint v2 aceita o mesmo formato de requisição do v1 (veja as tabelas de campos abaixo), mais um campo adicional por documento — documents[].stateCode (estado/província emissor, máx. 32 caracteres) — e aplica um pipeline mais rigoroso e seguro:

• Validação de documentos baseada em regras — por país + tipo de documento, regras configuradas por tenant podem exigir campos extras (ex.: stateCode para carteiras de motorista dos EUA) e aplicar regex de formato. Violações retornam 422 VALIDATION_ERROR com erros por campo em errors["documents.{i}.{field}"], e nada é persistido.
• Verificação síncrona de número KYC — quando a regra exige, o número do documento é verificado no serviço KYC Inyo360 durante a requisição. Uma rejeição do KYC retorna 422 com o detalhe; se o serviço KYC estiver indisponível, a requisição falha de forma segura com 502 KYC_UPSTREAM_ERROR (repita a requisição).
• Vereditos de verificação registrados — documentos verificados carregam kyc_verdict/kyc_verified_at nos registros de documentos da pessoa.
• Mesma idempotência do v1: se existir uma pessoa com o mesmo externalId, a pessoa existente é retornada com 200; uma nova pessoa retorna 201.

Tecnicamente, nenhum campo é obrigatório para criar uma pessoa — mas, para usá-la como remetente, ela deve atingir pelo menos o Nível de Conformidade 1, o que normalmente exige nome, sobrenome, endereço e número de telefone.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "birthDate": "1990-01-15",
  "phoneNumber": "+15551234567",
  "gender": "Male",
  "externalId": "your-internal-id-001",
  "address": {
    "countryCode": "US",
    "stateCode": "CA",
    "city": "San Francisco",
    "line1": "123 Market St",
    "zipcode": "94105"
  },
  "documents": [
    {
      "type": "drivers_license",
      "document": "D12345678",
      "countryCode": "US",
      "stateCode": "CA",
      "expireDate": "2030-06-30"
    }
  ],
  "occupation": "Software Engineer"
}'

Campos da Requisição

Tipos de Documento Aceitos

Nos endpoints v2, documents[].type usa valores em minúsculas, seguindo o mesmo padrão da solução KYC:

Observe o plural drivers_license — o v2 corrige o singular DRIVER_LICENSE do v1 para alinhar com o padrão KYC. Para uma migração tranquila, o v2 também aceita os valores legados em maiúsculas do v1 e o singular driver_license (todos comparados sem distinção de maiúsculas e normalizados), mas novas integrações devem enviar os valores em minúsculas.

Estes são números de documento declarados — para enviar imagens de documentos para verificação, use os endpoints de envio de documentos.

ⓘ O obsoleto v1 PATCH /people/{personId} aceita um conjunto mais restrito para documents[].type (PASSPORT, DRIVER_LICENSE, DNI, CC, CPF, ID, SSN, ITIN) e restringe documents[].countryCode a US, BR, CO, PE, KE. O v2 PATCH /v2/people/{personId} não tem essa restrição — suas regras de documentos espelham exatamente a criação v2.

Exemplo de Resposta

{
  "id": "48066496-9445-41b7-acbe-85e069a77cb7",
  "firstName": "John",
  "lastName": "Doe",
  "mainAddressId": "9c2ea7e5-51a2-4ea1-83cf-8948754486f8",
  "phoneNumber": "+15551234567",
  "email": "[email protected]",
  "gender": "Male",
  "birthDate": "1990-01-15",
  "externalId": "your-internal-id-001",
  "updatedAt": "2025-01-15T12:00:00",
  "documents": [],
  "occupation": "Software Engineer",
  "documentId": null,
  "sourceOfFundsId": null,
  "employerName": null,
  "employerAddressId": null
}

Guarde o id retornado — este é o senderId usado em todas as chamadas subsequentes da API.

Notas de comportamento:

• Idempotente em externalId — se uma pessoa com o mesmo externalId já existir no seu tenant, POST /people retorna a pessoa existente em vez de criar uma duplicata.
• Remetentes devem ter 18+ — birthDate é rejeitado se a pessoa for menor de 18 anos.
• Documentos são append-only — atualizar os documentos de uma pessoa insere novos registros e aposenta os antigos, preservando a trilha de auditoria de conformidade.

Atualizando um Remetente (v2 — Recomendado)

Endpoint: PATCH /organizations/{tenant}/v2/people/{personId}
Autenticação: Nível de tenant

⚠️ O endpoint v1 PATCH /organizations/{tenant}/people/{personId} está obsoleto. A atualização v2 aplica a mesma validação baseada em regras e verificação síncrona de número KYC da criação v2, e suas regras de documentos espelham exatamente a criação (a atualização v1 aceitava um conjunto mais restrito de documentos).

Apenas os campos incluídos no corpo da requisição são atualizados; campos omitidos permanecem inalterados. Os documentos são aditivos — cada atualização adiciona novos registros de documentos e o histórico permanece visível.

curl --request PATCH \
  --url https://{FQDN}/organizations/$TENANT/v2/people/$PERSON_ID \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "occupation": "Consultant",
  "documents": [
    {
      "type": "drivers_license",
      "document": "D87654321",
      "countryCode": "US",
      "stateCode": "CA",
      "expireDate": "2031-01-31"
    }
  ]
}'

Verificação de Endereço

Use o endpoint de checagem de endereço para pré-validar um endereço antes de criar ou atualizar um remetente. Ele aplica as mesmas regras de validação por país (incluindo formatos de código postal por país) dos endpoints de gravação reais, portanto uma checagem aprovada aqui significa que o endereço será aceito no POST /people.

curl --request GET \
  --url "https://{FQDN}/organizations/$TENANT/addresses/check?countryCode=US&stateCode=CA&city=San+Francisco&line1=123+Market+St&zipcode=94105" \
  --header "x-api-key: $API_KEY"

Parâmetros de query: line1, city, stateCode e countryCode são obrigatórios; zipcode é validado contra as regras de formato do país de destino.

Criando Remetentes Empresariais (KYB)

Para casos de uso B2B, você pode criar uma empresa como remetente:

Endpoint: POST /organizations/{tenant}/companies
Autenticação: Nível de tenant

Empresas seguem um sistema de níveis de conformidade semelhante, mas com campos obrigatórios diferentes (registro empresarial, EIN, etc.). Entre em contato com seu gerente de conta Inyo para a configuração de KYB específica do seu tenant.

Níveis de Conformidade

Estes níveis são personalizáveis por tenant. Veja Limites por Nível de Confiança para detalhes.

Boas Práticas

• Onboarding progressivo — Colete apenas os campos do Nível 1 no cadastro. Solicite mais dados quando o usuário precisar de limites maiores.
• Pré-valide endereços — Use o endpoint de checagem de endereço antes de criar o remetente para evitar retenções (holds).
• Sincronize o estado de conformidade — Após atualizações de perfil, verifique novamente o nível de conformidade para saber se ele foi elevado.
• Trate usuários restritos — Se um remetente estiver Restricted, consulte GET /participants/{id}/complianceLevels para entender o motivo e qual ação é necessária.

Páginas Relacionadas

• Limites por Nível de Confiança — Verifique e eleve níveis de conformidade
• Verificação de Documentos — Sessões de verificação KYC e verificação de documentos
• Dados de Teste — Cenários de teste em sandbox para fluxos de conformidade

Todos os Endpoints