API e documentação

Uma chave. Cada módulo.

A maioria dos softwares empresariais oferece uma API por produto — uma para o POS, outra para o stock, uma terceira para faturas, cada uma com a sua própria autenticação e a sua própria forma de gerir datas. Kardopal tem uma. A mesma chave, o mesmo URL base e a mesma gramática de consulta alcançam 129 recursos em 29 módulos.

Criar uma chave API Veja o que alcança
29
Módulos
129
Recursos
1
Chave, um URL base
200
Linhas por página, máx.

Porque vale a pena desenvolver sobre esta API

Seis coisas que são verdade aqui e geralmente não são.

Descreve-se a si próprio

Aceda ao URL base e a API devolve o seu próprio catálogo — cada módulo que a sua chave pode ver, cada recurso dentro dele, quais os campos pesquisáveis e quais os filtráveis. Não precisa desta página para escrever a integração; precisa dela para decidir fazê-lo.

Permissões que realmente controlam o acesso

Os âmbitos, rotas e os "permission pills" na aplicação são gerados a partir de uma lista, para que uma permissão não possa ser oferecida a menos que haja um endpoint por trás dela. Uma chave com âmbito para itens obtém itens — pedir-lhe a folha de pagamentos retorna 403, não uma página vazia e silenciosa.

Uma gramática de consulta, em todo o lado

Pesquisar, desde, até, saltar e Aceder significam o mesmo nas faturas e nos movimentos de stock. Aprenda o formato uma vez e cada um dos 133 recursos responde a ele.

A sua instância, e só a sua

Cada tabela tem um ID de inquilino e cada consulta é limitada ao inquilino da própria chave antes de chegar à base de dados. Não há leitura entre inquilinos que possa estar errada, porque não há nenhum parâmetro que possa pedir uma.

Os campos mantêm-se consistentes

A lista de campos é lida do esquema em tempo real no arranque, em vez de ser mantida manualmente. Uma nova coluna aparece sozinha; uma eliminada nunca pode deixar uma referência pendente na documentação ou um erro 500 na primeira chamada.

Apenas leitura, propositadamente

As chaves leem; nunca escrevem. Uma integração que corre mal não pode anular uma fatura ou mover stock. Tudo o que altera um registo passa pela aplicação ou por um login de funcionário, onde é atribuído a uma pessoa e fica no registo de auditoria.

Começar num pedido

Tudo é um GET. Se pode usar curl, pode usar isto.

GET /api/v1Todo o catálogo que a sua chave pode ver
curl https://api.kardopal.com/api/v1 \
  -H "X-API-Key: kp_live_…"
GET /api/v1/meVerificação de sanidade — de quem é esta chave e o que pode ler
{
  "authType": "api_key",
  "tenant": { "name": "Nova Retail", "plan": "pro" },
  "scopes": ["items", "sales", "pos"]
}
GET /api/v1/items?search=lamp&take=2Qualquer recurso, mesma forma
{
  "resource": "items",
  "scope": "items",
  "total": 41,
  "skip": 0,
  "take": 2,
  "hasMore": true,
  "data": [ { "id": "…", "name": "Desk Lamp LED" } ]
}
GET /api/v1/meta/countsContagem de linhas por recurso — veja que dados realmente existem
curl https://api.kardopal.com/api/v1/meta/counts \
  -H "X-API-Key: kp_live_…"

Os cinco parâmetros

ParâmetroFazNotas
PesquisarCorrespondência sem distinção entre maiúsculas e minúsculas nos campos pesquisáveis do recurso.Quais são esses campos está listado em /meta
desdeApenas registos a partir desta dataAplica-se ao campo pelo qual o recurso é ordenado
atéApenas registos até esta dataCombinar com desde para uma janela
saltarDeslocamento no conjunto de resultadosPredefinição: 0
AcederQuantas linhas devolverPredefinição de 50, limite de 200

Os recursos também aceitam filtros de correspondência exata nos seus próprios campos declarados — ?status=pago, ?warehouseId=… — e cada um anuncia quais são. Cada resposta de lista contém total e temMais, para que a paginação seja um ciclo, não uma suposição.

O que a API alcança

29 módulos, 129 recursos. Cada cartão é uma permissão que pode conceder a uma chave — e a etiqueta cinzenta é onde os mesmos registos vivem na aplicação do seu telefone.

Contactos

2

Clientes, fornecedores e os segmentos a que pertencem.

contactossegmentos de contacto
contactos Contactos

Artigos

7

O catálogo: produtos, variantes, marcas, tabelas de preços e unidades.

itenscategoriasmarcasvariantes de itemlistas-de-preçosunidades+1 mais
itens Artigos

Inventário

7

Armazéns, níveis de stock, movimentos, lotes, números de série e localizações.

armazénsmovimentos-de-stockníveis de stocklotessériescontagens-de-stock+1 mais
inventário Inventário

Vendas

7

Faturas, orçamentos, encomendas, notas de crédito e pagamentos.

faturasestimativasencomendas de vendanotas de créditopagamentosfaturas-recorrentes+1 mais
vendas Vendas

POS

11

Caixas, turnos, recibos, mesas e cada venda que passou pelo balcão.

vendas-posturnos-posterminais-POSutilizadores-posmesas-posáreas-de-mesa-pos+5 mais
pos POS

CRM

4

Leads, negócios, pipelines e propostas.

oportunidades de negócionegóciospipelinespropostas
crm CRM

Compras

5

Ordens de compra, pedidos, devoluções, faturas e pagamentos a fornecedores.

ordens-de-comprapedidos-de-compradevoluções-de-comprasfaturaspagamentos-a-fornecedores
compra Compras

Contabilidade

5

Despesas, contas bancárias, transações e taxas de imposto.

despesascategorias-de-despesascontas-bancariastransações-bancáriastaxas-de-imposto
contabilidade Contabilidade

Marketing

4

Campanhas, destinatários, páginas de destino e submissões de formulários.

campanhasdestinatários-da-campanhapáginas de destinoenvios de formulários
marketing Marketing

HR

8

Pessoas, departamentos, licenças, recibos de vencimento, assiduidade e contratação.

colaboradoresdepartamentospedidos-de-licençarecibos de vencimentoassiduidadeofertas-de-emprego+2 mais
hr HR

Folha de horas

2

Registos de tempo e os projetos aos quais estão atribuídos.

registos-de-tempoprojetos de folha de horas
folha de horas Folha de horas

Projetos

3

Projetos, fases e os custos associados.

projetosfases-do-projetocustos-de-projeto
projetos Projetos

Reservas

3

Marcações, serviços agendáveis e o pessoal que os presta.

reservasserviços de reservaagendamento-pessoal
reservas Reservas

Serviço de Campo

7

Trabalhos, técnicos, ordens de serviço, contratos e equipamentos.

tarefas-de-campotécnicospedidos-de-serviçocontratos-de-serviçoordens-de-trabalhofichas-de-trabalho+1 mais
serviço_de_campo Serviço de Campo

Logística

5

Envios, motoristas, veículos, zonas e transportadoras.

enviosmotoristasveículoszonas-de-entregatransportadoras
logística Logística

Helpdesk

5

Tickets, políticas de SLA, artigos de ajuda e a base de conhecimento.

ticketspedidos de clientesartigos-de-ajudabase-de-conhecimentopolíticas-sla
suporte Helpdesk

Pós-venda

5

Devoluções, reclamações de garantia, reparações e registos de produtos.

rmaspedidos-de-garantiaregistos-de-garantiareparaçõesregistos-de-produto
pós-venda Pós-venda

Aluguer

3

Ativos alugáveis, contratos de aluguer e as suas linhas.

ativosaluguereslinhas de aluguer
aluguer Aluguer

Restaurante

2

O menu e os pedidos feitos a partir dele.

itens-de-menupedidos de menu
restaurante F&B

Fila

5

Pedidos, serviços, balcões, filiais e os ecrãs de exibição.

senhas-de-filaserviços-de-filacontadores-de-filafilas-balcõesecrãs-de-fila
fila Fila

Fidelidade

6

Membros, contas, níveis, recompensas e transações de pontos.

membros-de-fidelidadecontas-de-fidelidaderecompensas-de-fidelidadeníveis-de-fidelidadetransações-de-fidelidadecupões-de-fidelidade
fidelidade Fidelidade

Localizações

2

Locais e filiais.

localizaçõesfiliais
localizações Localizações

IOT

6

Dispositivos, locais, caixas, alertas, eventos e conteúdo de sinalização.

dispositivos-iotlocais-iotalertas-ioteventos-iotiot-boxesconteúdo-de-sinalética-iot
iot IOT Hub

Estúdio de IA

3

Ativos gerados, os projetos que os contêm e o histórico de tarefas.

ativos-iaprojetos-iaai-jobs
ai_studio Estúdio de IA

Commerce

3

Membros da rede, pedidos de cotação e cobranças.

membros da redepedidos-de-orçamentocoleções
comércio Commerce

Assinatura eletrónica

2

Pedidos de assinatura e as assinaturas recolhidas.

pedidos de assinaturaassinaturas
assinatura Assinatura eletrónica

Aprovações

2

Pedidos de aprovação e as regras que os encaminham.

pedidos-de-aprovaçãoregras-de-aprovação
aprovações Aprovações

Ficheiros

2

Ficheiros carregados e documentos digitalizados.

ficheirosdocumentos-digitalizados
ficheiros Ficheiros

Atividade

3

O feed de atividade, o registo de auditoria e as notificações.

atividadesregistos de auditorianotificações
Por telefone

Cada módulo que a API lê, a sua equipa pode abrir na palma da mão

Esta é a parte que geralmente não é verdade. Muitas plataformas expõem uma API abrangente e depois lançam uma aplicação móvel que faz três coisas — aprovar, visualizar, notificar. A aplicação da Kardopal é o produto, não um complemento: todos os 29 módulos acima têm ecrãs reais, e o telemóvel é onde a maior parte do trabalho realmente acontece.

  • Leia, depois aja. A sua integração obtém um nível de stock; a pessoa que tem de o corrigir abre o mesmo registo, ajusta-o e este é assinado em seu nome.
  • Digitalize, fotografe, assine. A leitura de códigos de barras, a captura de documentos e a assinatura eletrónica são nativas do telemóvel — não têm um equivalente de desktop que valha a pena usar.
  • Tolerante a falhas de rede no balcão. O POS, o ecrã da cozinha e o ecrã de fila continuam a funcionar quando a ligação falha.
  • Mesmo login, mesmos dados, 20 idiomas. Incluindo da direita para a esquerda, para que uma equipa que fale árabe não esteja a ler um layout espelhado.
Ver a plataforma
A aplicação Kardopal a correr num telemóvel

Obter uma chave

Abra a aplicação, vá a Plataforma → Chaves API.As chaves são criadas por um proprietário ou administrador no seu próprio inquilino. Ninguém na Kardopal as emite por si.
Selecione apenas os módulos de que a integração necessita.Um widget de montra precisa de itens. Não precisa de hr. Chaves estreitas falham em segurança.
Envie-o como um cabeçalho, nunca no URL.X-API-Key: kp_live_… — as query strings acabam em registos, proxies e histórico do navegador.
Gire criando primeiro a nova chave.Ambos funcionam ao mesmo tempo, para que possa mover o tráfego e revogar o antigo sem tempo de inatividade.

Desenvolva algo sobre ele

A API documenta-se a si mesma: crie uma chave na aplicação, aponte curl no URL base, e devolve cada módulo, recurso e campo pesquisável que essa chave pode alcançar.

Criar uma chave API