API de Parceiros | SimplesFika

Como funciona

Voce mantem o catalogo da loja parceira no SimplesFika a partir do seu proprio sistema. E uma integracao em 3 passos:

O lojista gera a sua chave. No painel da loja, em Integracoes → API para outros sistemas, ele cria a chave com as permissoes certas e envia pra voce junto com o endereco da API.
Voce chama a API. Cadastra, atualiza, controla estoque e desativa produtos com requisicoes HTTP simples (JSON).
A loja reflete. Preco, estoque e SKU dos produtos que voce gerencia passam a ser controlados por voce; o lojista mantem fotos, descricao e SEO.

Integrar com ajuda de IA

A documentacao completa tambem esta em formatos que assistentes de IA e geradores de codigo leem direto. Entregue um deles para a sua IA:

Markdown completo: contrato, regras de posse, validacoes, erros, algoritmo recomendado e exemplo em Python, num unico arquivo.
OpenAPI 3.1: para gerar clientes (Postman, Insomnia, openapi-generator) ou dar a IA os schemas exatos.
llms.txt: indice padrao que aponta os dois arquivos acima.

Sugestao de pedido para a sua IA

Leia a documentacao em https://simplesfika.com/docs/api-parceiros-v1.md
e a especificacao em https://simplesfika.com/docs/openapi-parceiros-v1.json.
Escreva a integracao do meu sistema com a API de Parceiros SimplesFika:
- guarde dominio e chave de cada loja fora do codigo;
- sincronize produtos simples por SKU com PUT e o estoque com PATCH;
- trate os erros pelo campo "code" como a documentacao indica;
- respeite o header Retry-After no 429 e repita 5xx com espera crescente.

Autenticacao

Toda requisicao usa o cabecalho X-Partner-Key com a chave da loja. Uma chave por loja, gerada pelo lojista no painel (ou pela nossa equipe, se ele preferir). As respostas seguem o formato:

{ "ok": true, "data": { ... } }

{ "ok": false, "error": "Mensagem legivel", "code": "CODIGO_ESTAVEL" }

Exemplo de requisicao

curl -X PATCH https://<dominio-da-loja>/api/partner/v1/products/CAMISA-AZUL-M/stock/ \
  -H "X-Partner-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"estoque": 7}'

Referencia da API

Base: https://<dominio-da-loja>/api/partner/v1/. O produto e identificado pelo SKU. O v1 cobre produtos simples (1 SKU = 1 produto).

GET /api/partner/v1/products/

Lista os produtos que voce gerencia (para reconciliacao). Escopo catalog:read.

POST /api/partner/v1/products/

Cria um produto. Retorna 409 se o SKU ja existe. Escopo catalog:write.

curl -X POST https://<dominio-da-loja>/api/partner/v1/products/ \
  -H "X-Partner-Key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"sku": "CAMISA-AZUL-M", "nome": "Camisa Azul M", "preco": "79.90", "estoque": 12}'

PUT /api/partner/v1/products/{sku}/

Cria ou atualiza por SKU (idempotente). Atualiza preco/estoque; o nome so e definido na criacao. Escopo catalog:write. Para assumir um produto que o lojista ja cadastrou com o mesmo SKU, a chave precisa do escopo catalog:link, que o lojista marca como "Assumir produtos ja cadastrados" ao criar a chave.

PATCH /api/partner/v1/products/{sku}/stock/

Atualiza somente o estoque (valor absoluto). Escopo stock:write.

DELETE /api/partner/v1/products/{sku}/

Desativa o produto (some da vitrine, preserva o historico). Escopo catalog:write.

Erros

Erros vem com um code estavel, para o seu sistema tratar de forma programatica:

HTTP	code	Quando acontece
401	`MISSING_PARTNER_KEY`	Cabecalho X-Partner-Key ausente
403	`INVALID_PARTNER_KEY`	Chave invalida ou inativa
403	`INSUFFICIENT_SCOPE`	Chave sem permissao para a operacao
404	`PRODUCT_NOT_FOUND`	SKU nao existe (em PATCH/DELETE)
409	`SKU_ALREADY_EXISTS`	POST com um SKU que ja existe
409	`PROMOTIONAL_PRICE_ACTIVE`	Produto com promocao ativa (desative antes de mudar o preco)
409	`EXTERNAL_SOURCE_CONFLICT`	Produto ja gerenciado por outra integracao
409	`PRODUCT_NOT_LINKED`	Produto cadastrado pelo lojista e ainda nao vinculado a sua integracao
409	`VARIANT_STOCK_NOT_SUPPORTED`	Produto com grade/variacao (nao suportado no v1)
409	`PRODUCT_MODE_NOT_SUPPORTED`	Produto do tipo kit, link externo ou encomenda
422	`VALIDATION_ERROR`	Payload invalido (ex.: estoque nao numerico, preco zero, negativo ou com mais de 2 casas)
429	`RATE_LIMITED`	Excedeu o limite de requisicoes (espere os segundos do cabecalho `Retry-After`)

Suporte e parceria

Quer integrar seu sistema ao SimplesFika ou precisa da sua chave de parceiro? Fale com a nossa equipe.

Fale com a gente

Ajudamos na integracao e, se o lojista preferir, emitimos a chave por ele.

[email protected] (83) 99676-0205

Integre seu sistema ao SimplesFika