Panamah Core

Baixar especificação da API:Download

API de distribuidores do Panamah®

Introdução

O Panamah possui uma API de entrada, usada atualmente pelos o SDKs. Através dessa API, é possível gerenciar assinantes e realizar a subida de arquivos em lotes com informações diversas, como vendas, produtos, lojas e etc. Chamamos essa API de Panamah Core.

Get Started

O Panamah Core possui duas frentes, o Admin e o Stream. Atráves do Admin é possível gerenciar assinantes, criando, buscando e atualizando. O Stream é encarregado de subir os arquivos em lote, como movimentações de um assinante. É necessário em ambos os casos, a utilização o Authorization Token.

Autenticação

Access Token

Ao realizar a autenticação na rota /stream/auth é enviado um access token e um refresh token, o primeiro deverá ser utilizado para as demais requisições nas rotas de Stream. Um exemplo de token:

IMPORTANTE

O Acess Token irá expirar com um determinado tempo, por isso será necessário realizar uma nova autenticação ou utilizar a rota de refresh com o Refresh Token.

Security Scheme Type	API Key
Header parameter name:	Authorization

Authorization Token

Cada parceiro possui um token de autorização, ele é utilizado para autenticar e identificar qual parceiro está utilizando a API.

Security Scheme Type	API Key
Header parameter name:	Authorization

X SDK Identity

Cada SDK possui um identificador cadastrado no Panamah. Ele servirá para identificar de qual plataforma está sendo enviada a requisição. Para parceiros que queiram utilizar API. esse cabeçalho é constituido com panamah-api1.0.0.

Security Scheme Type	API Key
Header parameter name:	x-sdk-identity

Endpoint de gerenciamento de assinantes

/admin/assinantes

Essas informações definem os campos obrigatórios nas requisições e a estrutura minima do payload na resposta. É possível enviar outros campos baseados nos esquemas de assinantes, assim como receber mais informações nas rotas de GET e PUT.

Cadastra um novo assinante no Panamah

Retorna os dados do assinante cadastro no Panamah.

Authorizations:

Authorization TokenX SDK Identity

Request Body schema: application/json

id	string Id da assinante
nome	string Nome do assinante
fantasia	string Nome fantasia do assinante
cnpj	string CNPJ do assinante

Responses

Exemplos de requisição

Payload
Node + Request
Shell + Curl
Python + Python3
Php + Http1

Content type

application/json

{"id": "string",
"nome": "string",
"fantasia": "string",
"cnpj": "string"
}

Exemplos de resposta

201
422
500

Content type

application/json

{"id": "string",
"nome": "string",
"fantasia": "string",
"ativo": true,
"oficial": true,
"creatorHost": "string",
"creatorSDKIdentity": "string",
"cnpj": "string",
"softwaresAtivos": [ ],
"softwaresEmContratosDeManutencao": [ ],
"planoUso": { }
}

Busca informações de assinante no Panamah

Retorna os dados de um assinante previamente cadastro no Panamah.

Authorizations:

Authorization TokenX SDK Identity

path Parameters

id

required

string

ID do Assinante

Responses

Exemplos de requisição

Node + Request
Shell + Curl
Python + Python3
Php + Http1

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://panamah.io/api/v2/admin/assinantes/{id}',
  headers: {Authorization: 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Exemplos de resposta

200
400
500

Content type

application/json

{"id": "string",
"nome": "string",
"fantasia": "string",
"ativo": true,
"oficial": true,
"creatorHost": "string",
"creatorSDKIdentity": "string",
"cnpj": "string",
"softwaresAtivos": [ ],
"softwaresEmContratosDeManutencao": [ ],
"planoUso": { }
}

Atualiza um assinante no Panamah

Retorna os dados do assinante atualizado no Panamah.

Authorizations:

Authorization TokenX SDK Identity

path Parameters

id

required

string

ID do Assinante

Request Body schema: application/json

id	string Id da assinante
nome	string Nome do assinante
fantasia	string Nome fantasia do assinante
ativo	boolean Informação se assinante está ativo
oficial	boolean Informação se assinante é oficial
creatorHost	string Host criador
creatorSDKIdentity	string SDK criador
cnpj	string CNPJ do assinante
softwaresAtivos	array Softwares ativos do assinante
softwaresEmContratosDeManutencao	array Software em contrados de manutenção do assinante
planoUso	object Planos do assinante

Responses

Exemplos de requisição

Payload
Node + Request
Shell + Curl
Python + Python3
Php + Http1

Content type

application/json

{"id": "string",
"nome": "string",
"fantasia": "string",
"ativo": true,
"oficial": true,
"creatorHost": "string",
"creatorSDKIdentity": "string",
"cnpj": "string",
"softwaresAtivos": [ ],
"softwaresEmContratosDeManutencao": [ ],
"planoUso": { }
}

Exemplos de resposta

200
401
422
500

Content type

application/json

{"id": "string",
"nome": "string",
"fantasia": "string",
"ativo": true,
"oficial": true,
"creatorHost": "string",
"creatorSDKIdentity": "string",
"cnpj": "string",
"softwaresAtivos": [ ],
"softwaresEmContratosDeManutencao": [ ],
"planoUso": { }
}

Endpoint de envio de dados

/stream

Realiza autenticação no Panamah

Retorna tokens para realização de envio de dados

Authorizations:

Authorization TokenX SDK Identity

Request Body schema: application/json

ts

string

timestamp da requisição É possível obter aqui

assinanteId

string

ID do assinante

key

string

chave calculada pelo o secret, assinanteId e ts. É possível obter aqui com o código abaixo.


  const Sha1 = require("crypto-js/sha1");
  const Base64 = require("crypto-js/enc-base64");

  const secretExample = '';
  const assinanteIdExample = '';
  const tsExample = '';

  console.log(Base64.stringify(Sha1(secretExample+assinanteIdExample+tsExample)));

Responses

Exemplos de requisição

Payload
Node + Request
Shell + Curl
Python + Python3
Php + Http1

Content type

application/json

{"ts": "string",
"assinanteId": "string",
"key": "string"
}

Exemplos de resposta

201
401
500

Content type

application/json

{"accessToken": "string",
"refreshToken": "string"
}

Atualiza tokens de acesso

Realiza atualização e retorna tokens para realização de envio de dados. No header Authorization, deverá ser usado o valor do refreshToken obtido anteriomente.

Authorizations:

Access TokenX SDK Identity

Responses

Exemplos de requisição

Node + Request
Shell + Curl
Python + Python3
Php + Http1

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://panamah.io/api/v2/stream/auth/refresh',
  headers: {Authorization: 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Exemplos de resposta

200
403
500

Content type

application/json

{"accessToken": "string",
"refreshToken": "string"
}

Envia dados para o Panamah

Realiza o envio de dados para o Panamah atraves de arquivos em lote

Authorizations:

Access TokenX SDK Identity

Request Body schema: application/json

Formato de arquivos .pdt

Array ()

assinanteId	string ID do assinante
op	string Enum: "update" "delete"
tipo	string Enum: "ASSINANTE" "REVENDA" "SECAO" "GRUPO" "SUBGRUPO" "HOLDING" "LOJA" "META" "FORMA_PAGAMENTO" "FUNCIONARIO" "ACESSO" "CLIENTE" "FORNECEDOR" "PRODUTO" "EAN" "TROCA_FORMA_PAGAMENTO" "TROCA_DEVOLUCAO" "EVENTO_CAIXA" "VENDA" "COMPRA" "LOCAL_ESTOQUE" "ESTOQUE_MOVIMENTACAO" "TITULO_PAGAR" "TITULO_RECEBER"
data	object Corpo seguindo o exemplo dos esquemas descritos aqui

Responses

Exemplos de requisição

Payload
Node + Request
Shell + Curl
Python + Python3
Php + Http1

Content type

application/json

[{"assinanteId": "string",
"op": "update",
"tipo": "ASSINANTE",
"data": { }
}
]

Exemplos de resposta

201
400
500

Content type

application/json

{"sucessos": {"total": 0,
"itens": [{ }
]
},
"falhas": {"total": 0,
"itens": [{ }
]
}
}

Consulta dados pendentes do assinante

É possível consultar dados pendentes que ainda não foram processados com sucesso pela API Panamah. Atualmente, essa funcionalidade está disponível apenas para produtos.

Como o envio dos modelos de dados é independente e ocorre de forma assíncrona, pode acontecer de os dados de venda ficarem incompletos, justamente porque os produtos correspondentes ainda não foram processados.

A função de envio de dados pendentes é importante justamente para atenuar esses problemas e garantir que as informações de venda fiquem o mais completas possível. Por isso, é necessário acionar esse recurso periodicamente.

A resposta sempre retorna uma lista de pendências organizadas por assinante e tipo de recurso (ex.: PRODUTO). Cada item contém:

assinanteId → Identificador do assinante que possui pendências
models ou ids → Lista de modelos ou identificadores dos recursos pendentes (normalmente produtos ainda não sincronizados)

Esses objetos podem ser usados para:

Conferir quais registros ainda não foram enviados
Reprocessar/envia-los novamente
Monitorar consistência dos dados entre sua base e a Panamah

Authorizations:

Access TokenX SDK Identity

query Parameters

start	number >= 0 Default: 0 Índice de início para paginação, usado como `offset`. Define a partir de qual registro começar a retornar os dados pendentes. Útil para implementar paginação quando há muitos recursos pendentes.
count	number [ 1 .. 1000 ] Default: 100 Example: count=50 Número máximo de itens a serem retornados, usado como `limit`. Controla quantos recursos pendentes serão incluídos na resposta. Recomenda-se usar valores entre 10 e 100 para melhor performance.

Responses

Exemplos de requisição

Node + Request
Shell + Curl
Python + Python3
Php + Http1

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://panamah.io/api/v2/stream/pending-resources',
  qs: {start: 'SOME_NUMBER_VALUE', count: 'SOME_NUMBER_VALUE'},
  headers: {Authorization: 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Exemplos de resposta

200
400
500

Content type

application/json

{"35472867000228": {"PRODUTO": ["18974299",
"18974310",
"18974680"
]
}
}