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

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

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/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": "SSN",
      "document": "123456789",
      "countryCode": "US"
    }
  ],
  "occupation": "Software Engineer"
}'

Campos da Requisição

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

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

Apenas os campos incluídos no corpo da requisição são atualizados; campos omitidos permanecem inalterados.

curl --request PATCH \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "occupation": "Consultant",
  "documents": [
    {
      "type": "SSN",
      "document": "987654321",
      "countryCode": "US"
    }
  ]
}'

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
• Enviando Documentos — Envie documentos de identidade e de origem dos fundos
• Dados de Teste — Cenários de teste em sandbox para fluxos de conformidade

Todos os Endpoints

Documentação Interativa da API