Documentacao API

Documentacao API

Acesse os dados do seu aplicativo Inventory de forma programatica atraves da nossa API externa.

Visao geral

O que e a API?

A API externa fornece uma interface para acessar os dados do aplicativo Inventory a partir de programas externos.

Casos de uso

  • Automacao: Processamento em lote de documentos atraves de scripts
  • Integracao de terceiros: Sincronizacao de dados com outros servicos
  • Operacoes em massa: Criacao e compartilhamento em massa de modelos

Primeiros passos

Obtendo uma chave API

Para usar a API, voce primeiro precisa de uma chave API.

  1. Abra a tela de Perfil no aplicativo Inventory
  2. Encontre a secao Chave API
  3. Toque no botao Gerar chave
  4. Sua chave API sera exibida na tela

Importante: A chave API e mostrada apenas uma vez quando gerada. Certifique-se de copia-la e guarda-la em um local seguro. Se perder, precisara regenera-la.

Formato da chave API

As chaves API seguem este formato:

inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Comeca com o prefixo inv_
  • String codificada em Base64URL de aproximadamente 50 caracteres

Gerenciamento de chaves API

  • Regenerar: Revoga a chave existente e emite uma nova
  • Excluir: Remove completamente a chave API (acesso API desabilitado)

Autenticacao

Todas as requisicoes API requerem um cabecalho Authorization.

Token Bearer

Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Exemplo de requisicao

curl -H "Authorization: Bearer inv_your_api_key" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items"

Limitacao de taxa

O uso da API esta sujeito a limites.

Tipo de limite Limite Descricao
Por minuto 60 requisicoes Previne requisicoes excessivas
Mensal Varia por conta Determinado por contrato

Quando o limite e excedido

  • O codigo de status HTTP 429 Too Many Requests e retornado
  • Por favor aguarde e tente novamente mais tarde

Endpoints da API

URL base

https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1

APIs de leitura (GET)

Endpoint Descricao
GET /items Listar seus itens
GET /items/{token} Obter detalhes do item
GET /templates Listar seus modelos
GET /templates/{token} Obter detalhes do modelo
GET /templates/shared Listar modelos compartilhados
GET /user/stats Obter estatisticas do usuario

APIs de escrita (POST)

Endpoint Descricao
POST /templates Criar novo modelo
POST /templates/{token}/share Compartilhar modelo
POST /templates/revoke Revogar compartilhamento
POST /templates/{token}/send Enviar modelo

Referencia detalhada da API

GET /items - Listar itens

Recupera uma lista de itens (documentos) que voce possui.

Requisicao

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items?page=1&pageSize=20"

Parametros de consulta

Parametro Tipo Padrao Descricao
page number 1 Numero da pagina
pageSize number 20 Itens por pagina (max 100)
status string “active” Filtro de status (active, pending)
type string - Filtro de tipo (paper, stamp)

Resposta

{
  "success": true,
  "data": {
    "items": [
      {
        "token": "id_item_criptografado",
        "title": "Titulo do Item",
        "content": "Conteudo do Item",
        "type": "paper",
        "status": "active",
        "imageUrl": "https://...",
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 50,
      "totalPages": 3
    }
  }
}

POST /templates - Criar modelo

Cria um novo modelo (carimbo).

Requisicao

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "imageUrl": "https://example.com/image.png",
       "title": "Titulo do Modelo",
       "content": "Conteudo do Modelo",
       "commentMode": "independent",
       "keywords": ["produto:laptop", "preco:$1500BRL$"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates"

Corpo da requisicao

Campo Tipo Obrigatorio Descricao
imageUrl string Sim URL da imagem (HTTPS recomendado)
title string Sim Titulo (max 32 caracteres)
content string Sim Conteudo (max 1024 caracteres)
commentMode string Nao Modo comentario: “independent” ou “shared”
keywords string[] Nao Array de palavras-chave (max 128)

Formato de palavras-chave

As palavras-chave devem seguir o formato chave:valor.

Tipo Formato Exemplo
Geral chave:valor produto:caneta
Data chave:@AAAA-MM-DD@ inicio:@2025-01-15@
Telefone chave:#telefone# contato:#+55 11 91234-5678#
Local chave:%endereco% lugar:%Sao Paulo, Centro%
Valor chave:$valorMoeda$ preco:$50000BRL$

Resposta

{
  "success": true,
  "data": {
    "token": "id_modelo_criptografado",
    "title": "Titulo do Modelo",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates/{token}/share - Compartilhar modelo

Compartilha um modelo para que outros usuarios possam descobri-lo.

Requisicao

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "durationMinutes": 1440,
       "tags": ["TAG1", "TAG2"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/share"

Corpo da requisicao

Campo Tipo Obrigatorio Descricao
durationMinutes number Sim Duracao do compartilhamento (minutos). 60-43200 ou 0 (ilimitado)
tags string[] Sim Tags de busca (1-16, maiusculas auto)

Resposta

{
  "success": true,
  "data": {
    "shareToken": "id_compartilhamento_criptografado",
    "expiresAt": "2025-01-02T00:00:00Z",
    "tags": ["TAG1", "TAG2"]
  }
}

Codigos de erro

Quando uma requisicao API falha, os erros sao retornados neste formato:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descricao do erro"
  }
}

Lista de codigos de erro

Codigo Status HTTP Descricao
INVALID_API_KEY 401 Chave API invalida
API_KEY_EXPIRED 401 Chave API expirada
API_DISABLED 403 API desabilitada
RATE_LIMIT_EXCEEDED 429 Limite de requisicoes excedido
VALIDATION_ERROR 400 Entrada invalida
INVALID_TOKEN 400 Token invalido
NOT_FOUND 404 Recurso nao encontrado
FORBIDDEN 403 Acesso negado
RECIPIENT_NOT_FOUND 404 Destinatario nao encontrado

Recomendacoes de seguranca

  1. Proteger chaves API: Nunca exponha chaves API em repositorios publicos ou codigo cliente
  2. Usar HTTPS: Todas as requisicoes sao transmitidas via HTTPS
  3. Rotacao de chaves: Regenere chaves API periodicamente
  4. Privilegio minimo: Realize apenas operacoes necessarias

Contato

Se voce tiver problemas usando a API, entre em contato atraves da pagina Sugestoes.