Skip to main content
Esta página leva você de uma chave de API nova até uma lista paginada de pedidos. Todos os exemplos rodam no seu servidor, nunca em um navegador.

Antes de começar

  • Uma chave de API com os escopos clinics:read, catalog:read e orders:read. Veja Autenticação para saber como obtê-la.
  • Um destes: curl, Node.js 18 ou superior (que já inclui fetch), ou Python 3 com o pacote requests (pip install requests).
  • Os exemplos em JavaScript usam await no nível superior: salve-os em um arquivo terminado em .mjs.

Passos

1

Coloque a chave em uma variável de ambiente

Nunca escreva a chave no seu código. Exporte-a no terminal (ou carregue-a do seu gerenciador de segredos):
Todos os exemplos abaixo leem MUVEYA_API_KEY e chamam https://api.muveya.com.
2

Identifique a chave

GET /v1/me não exige escopo. Ela informa qual clínica odontológica a chave lê e quais escopos ela tem.
Resposta
Um 401 com api_keys.invalid significa que o cabeçalho ou a chave estão errados. Veja Respostas 401 e 403.
3

Liste suas unidades

GET /v1/clinics (escopo clinics:read) retorna todas as unidades da clínica odontológica em uma única página. GET /v1/warehouses funciona do mesmo jeito para os depósitos.
Resposta
Mantenha um mapa de clinicId para name: pedidos e análises se referem às unidades pelo id.
4

Liste os insumos do catálogo

GET /v1/catalog/items (escopo catalog:read) retorna todos os insumos do catálogo, qualquer que seja o status, em uma única página.
Resposta
Esta chave não tem catalog.cost:read, então os campos de custo ficam ausentes. Com esse escopo, cada insumo também traz costStatus e, quando há um custo registrado, cost, currency e costMeasurement. Confira costStatus antes de usar um valor: veja Custos.
5

Leia um pedido

Pegue um orderId de GET /v1/orders e leia-o com GET /v1/orders/{orderId} (escopo orders:read). O detalhe inclui as linhas e o plano de aprovação.
Resposta
O value do pedido e o patientRef de um pedido clínico nunca são retornados em /v1. Um pedido de outra clínica odontológica, ou um id que não existe, responde 404 com o código orders.not_found.
6

Percorra as páginas

GET /v1/orders é paginado. Peça até 200 pedidos por página e envie nextCursor de volta como cursor enquanto hasMore for true. Envie os mesmos filtros em todas as páginas.
Primeira página
Os pedidos vêm do mais antigo para o mais recente. O cursor é opaco: não o decodifique nem o construa. Veja Paginação para todas as regras.

Trate erros e limites

Dois hábitos deixam uma integração robusta desde o primeiro dia:
  1. Decida pelo code, não pelo texto. Todo erro é um documento de problema com um code estável e um requestId. Registre os dois. Veja Erros.
  2. Respeite o limite de uso. Cada chave tem um orçamento de requisições por minuto. Diante de um 429, espere os segundos indicados em Retry-After e tente de novo. Veja Limites de uso.

Próximos passos

Escolha os escopos

Receitas de privilégio mínimo para integrações comuns.

Exporte o resumo gerencial

Peça um CSV, acompanhe o status e verifique o checksum.

Fique em dia sem webhooks

Receitas de consulta periódica para pedidos, entregas e estoque.

Conecte um assistente de IA

O MCP usa um fluxo separado de login e autorização com OAuth.