KinologydevelopersReferência da API v1.0
GUIAS DE INTEGRAÇÃO

Sincronize seus pacientes

Crie, encontre e atualize registros sem perder a identidade no sistema parceiro.

Crie com versão zero

VERSAO_REGISTRO: 0 cria o registro. Nome, nascimento válido (YYYY-MM-DD), sexo M ou F e METADADOS.ID_REFERENCIA_EXTERNA são obrigatórios. A resposta de criação usa HTTP 201 e informa REFERENCIA_PACIENTE e a versão 1.

POST/contas/{CONTA}/pacientes/sincronizar
cURL
KIN_BASE_URL=https://api.exemplo.invalid
curl -X POST "$KIN_BASE_URL/v7/integracoes/contas/cta_0123456789abcdef0123456789abcdef/pacientes/sincronizar" \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'X-Correlation-ID: INTEGRACAO-EXEMPLO-001' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: INTEGRACAO-CADASTRO-001' \
  --data '{
  "VERSAO_REGISTRO": 0,
  "USUARIO_NOME": "Paciente Exemplo",
  "USUARIO_NASCIMENTO": "1990-04-15",
  "USUARIO_SEXO": "M",
  "METADADOS": {
    "ID_REFERENCIA_EXTERNA": "00158"
  }
}'

Localize pelo código externo

ID_REFERENCIA_EXTERNA é uma string exata de 1–100 caracteres, sensível à caixa e única por integração e conta. Preserve zeros iniciais, sem espaços nas extremidades. Use encodeURIComponent no segmento da URL. REFERENCIA_PACIENTE também pode ser usada na rota própria e deve ser tratada como opaca.

GET/contas/{CONTA}/pacientes/referencia_externa/{EXTERNA}
cURL
KIN_BASE_URL=https://api.exemplo.invalid
curl -X GET "$KIN_BASE_URL/v7/integracoes/contas/cta_0123456789abcdef0123456789abcdef/pacientes/referencia_externa/00158" \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'X-Correlation-ID: INTEGRACAO-EXEMPLO-001'

Atualize com controle de versão

Consulte o registro e envie VERSAO_REGISTRO atual, METADADOS.ID_REFERENCIA_EXTERNA e apenas os campos a alterar. Campos omitidos são preservados. Não troque a referência externa. Em 409 VERSAO_CONFLITANTE, consulte novamente e revise a intenção antes de enviar outra atualização.

Repita sem duplicar

Sincronização e CSV exigem Idempotency-Key: 8–100 caracteres ASCII alfanuméricos, ponto, hífen ou underscore. Retente a mesma operação com a mesma chave e corpo. Nova intenção exige chave nova. Repetir chave com outro corpo retorna 409 IDEMPOTENCIA_CONFLITANTE. Replay idempotente é diferente de conflito de versão.

Metadados autorizados

Neste exemplo, use apenas ID_REFERENCIA_EXTERNA. Outras chaves exigem autorização Kinology e valores string de 1–200 caracteres, até 20 chaves. Esses metadados adicionais não são filtros genéricos. As relações e autorizações próprias do sistema integrador permanecem sob sua responsabilidade.

Todos os exemplos são sintéticos. Execute chamadas reais somente no seu servidor, em ambiente autorizado.
Experimentar no laboratório