API WORLDORG – VERSÃO 1.00
www.worldorg.net

30 de Junho de 2008

Índice

1 Introdução

1.1 Passando Informações

1.2 Padrão do XML

1.3 Mensagens

2 Recuperando Informações

2.1 Limitando as Exibição

2.2 Estrutura do XML com dados

2.3 Estrutura de Evento

2.4 Estrutura de Contatos

2.5 Estrutura de Feeds e Marcadores

2.6 Estrutura de Amigos e Amigos Não Aprovados

2.7 Estrutura de Notas

2.8 Estrutura de Mensagens

2.9 Estrutura de Países

3 Removendo Registros

4. Incluindo um Novo Registro

4.1 Campos de Eventos

4.2 Campos de Contato

4.3 Campos de Feeds e Marcadores

4.4 Campos de Notas

4.5 Campos de Amigos

5. Alterando Registros

6 Testar Login

7 Links de Referência

1 Introdução

Cada função tem sua própria endereço para ser acesso e todas as informações são retornadas em XML, usando a codificação ISO-8859-1. O XML é apresentando nos padrões. Na tabela a seguir são mostrados cada URI para chamar as funções.

Os domínios usados usam SSL.

Ação	URI
Retornar Dados:	https://www.worldorg.net/api/getdados.php
Incluir Dados:	https://www.worldorg.net/api/indados.php
Alterar Dados:	https://www.worldorg.net/api/eddados.php
Remover Dados:	https://www.worldorg.net/api/deldados.php
Testar Login:	https://www.worldorg.net/api/login.php

Tabela 1: Ações e suas URI's

1.1 Passando Informações

Como as páginas chamadas são em PHP você deve passar sempre o nome do usuário e a senha em um hash MD5.

Para quem não trabalha em PHP a documentação vai explicar como passar esses dados, que são bem simples de entender.

As informações que são padrão para cada página, são: usuário, senha e ação, com os seguintes nomes dos parâmetros.

user: nome do usuário

pwd: senha do usuário

action: ação que será executada

No exemplo a seguir irá ser chamado um retorno de dados que lista os eventos de uma pessoa, que tem o usuário como teste, a senha como teste e a ação com o valor 1.

https://www.worldorg.net/api/getdados.php?user=teste &pwd=teste &action=1

Observação: no exemplo não foi gerado um hash MD5 da senha, mas ele é obrigatório.

Note que após o nome da arquivo getdados.php vem um “?”, este interrogação significa que a partir dali serão passados os parâmetros, e logo depois de cada nome de parâmetro vem um “=” que significa que aquele campo receberá o valor que estiver depois dele. E para separar os parâmetros é usado o “&”.

1.2 Padrão do XML

Todas as páginas geram um XML de resposta, esses XML seguem o seguinte padrão:

<message>MENSAGEM</message>

</resultadoxml>

Todos as respostas vem dentro do nodo <resultadoxml>, e depois vem os nodos filhos. Para exibir as mensagens de sucesso ou falha numa operação existe o nodo <message>, aonde estão as mensagens.

1.3 Mensagens

No quadro a seguir estão descritas as mensagens que são apresentadas no nodo <message>:

MENSAGEM	SIGNIFICADO
EMPTY DATA LOGIN	Os dados para login (usuário e senha) não foram informados.
EMPTY ACTION	Não foi informada uma ação.
NO LOGIN	Usuário ou senha foram informados errados.
ACTION NOT EXIST	A ação informada não existe.
OK	Tudo ocorreu bem.

Tabela 2: Mensagens e significados

2 Recuperando Informações

A partir de agora veremos como trabalhar com a recuperação de dados. A API retorna praticamente todos as categorias que o site possui: eventos, contatos, amigos, marcadores, feeds, mensagens e notas.

No quadro abaixo estão listados o que é retornado pelo getdados.php (esses códigos devem ser passados no action):

Código	Retorno
1	Eventos
2	Contatos
3	Feeds
4	Marcadores
5	Amigos
6	Amigos que ainda não foram aprovados
7	Notas
8	Mensagens
9	Países

Tabela 3: Código dos actions e seus retornos

2.1 Limitando as Exibição

O desenvolvedor pode especificar o total de itens a serem retornados, o máximo de 100 itens retornados por arquivo XML, mas caso seja necessário exibir um certo número de itens deve ser especificada a variável itens , se essa variável não for definida, ela receberá o total de 15 itens.

Para exibir os próximos 15 itens por exemplo, deve-se definir a variável limite, que irá valer 0 se não for definido No exemplo a seguir são exibidos os próximos 30 registros a partir do 15º registro no banco de dados.

https://www.worldorg.net/api/getdados.php?user=teste&pwd=teste&action=1&limite=15&itens=30

2.2 Estrutura do XML com dados

Todas as estruturas recebem um padrão, primeiro vem o nodo <resultadoxml> e dentro dele todos os resultados, cada resultado é exibido dentro de um nodo chamado <registro> , no final da estrutura existe o nodo <totalregistros>, o qual contém o total de itens recuperados.

Exemplo de XML com retorno de notas:

<titulo>Teste</titulo>

<nota>Teste</nota>

</registro>

<titulo>Teste 2</titulo>

</registro>

</resultadoxml>

2.3 Estrutura de Evento

Caso seja apenas necessário listar eventos que estejam compartilhados com amigos ou não deve se usar o parâmetro filtro, defina o valor “A” para receber apenas os itens compartilhados dos amigos, use o valor “N” para listar todos os eventos não compartilhados e deixe o parâmetro vazio ou não envie ele na requisição para listar ambos os resultados (recomenda-se não enviar ele na URL quando estiver vazio).

Caso seja necessário recuperar apenas eventos de uma data específica, deve-se passar o parâmetro datainicial, no formato DD/MM/YYYY, com a data que se deseja recuperar. Mas se for necessário recuperar eventos num período de datas, então são informados os parâmetros datainicial e datafinal, ambos no formato DD/MM/YYYY.

O arquivo XML de eventos conta com os seguintes nodos:

TAG	Descrição
codigo	código do evento
tagnome	nome da tag que classifica o evento
titulo	título do evento
descricao	descrição do evento
prioridade	prioridade (A = Alta, M = Média, B = Baixa)
situacao	situação do evento (R = Realizada, N = Não Realizada)
horario	horário do evento (Formato 00:00 – 23:59)
data	data do evento (Formato DD/MM/YYYY)
publico	se o evento está sendo compartilhado com os amigos (N = Não, A = Com amigos)
hora	apenas a hora (00 – 23)
minuto	Apenas o minuto do evento (00 – 59)
dia	Dia do evento (01 – 31)
mes	Mês do evento (01 – 12)
ano	Ano (YYYY)

2.4 Estrutura de Contatos

O arquivo XML de contatos conta com os seguintes nodos:

TAG	Descrição
codigo	codigo do contato
nome	nome do contato
cidade	cidade do contato
estado	estado do contato
pais	país do contato (no formato inteiro, referenciando a entidade de países)
codpostal	cep do contato
telefone	telefone do contato
celular	telefone celular do contato
email	e-mail do contato
site	site do contato
msn	msn do contato
icq	icq do contato
aim	aim do contato
yahoo	yahoo messenger do contato
gtalk	endereço do jabber/gtalk do contato
skype	skype do contato
tagnome	nome da tag que classifica o contato
informacoes	mais informações do contato

2.5 Estrutura de Feeds e Marcadores

O arquivo XML de feeds e marcadores conta com os seguintes nodos:

TAG	Descrição
codigo	código do feed/marcador
nome	nome do feed/marcador
url	url do feed/marcador
descricao	descrição do feed/marcador
tagnome	nome da tag que classifica feed/marcador

2.6 Estrutura de Amigos e Amigos Não Aprovados

O arquivo XML de amigos e amigos não aprovados conta com os seguintes nodos:

TAG	Descrição
nome	nome do amigo
sobrenome	sobrenome do amigo
email	e-mail do amigo
cidade	cidade do amigo
estado	estado do amigo
site	site do amigo
avatar	avatar do amigo com o endereço completo

2.7 Estrutura de Notas

O arquivo XML de notas conta com os seguintes nodos:

TAG	Descrição
codigo	código da nota
titulo	título da nota
nota	texto da nota

2.8 Estrutura de Mensagens

O arquivo XML de mensagens conta com os seguintes nodos:

TAG	Descrição
codigo	código da mensagem
msglida	armazena se a mensagem foi lida (S = Sim, N = Não)
mensagem	texto da mensagem
titulo	título da mensagem
autor	nome do autor da mensagem
data	data e hora em que a mensagem foi enviada
avatar	avatar do remetente

2.9 Estrutura de Países

O arquivo XML de países conta com os seguintes nodos:

Ps.: Esse XML somente é usado para pegar o código do país a ser usado nas inclusões e alterações de contatos)

TAG	Descrição
codigo	código da país
Nome	nome do país

3 Removendo Registros

Para remover os dados deve ser chamada a página deldados.php, e passar os parâmetros user, pwd, action e codigo. Esse último parâmetro é o código do item a ser removido do banco de dados.

Com esses parâmetros a URL ficaria do seguinte modo por exemplo:

https://www.worldorg.net/api/getdados.php?user=teste&pwd=teste&action=1&codigo=1

No exemplo acima foram passados os valores “teste” como nome e senha do usuário, e o action valendo 1 (evento) e o código do evento valendo 1.

No quadro abaixo estão listados o que é retornado pelo deldados (esses códigos devem ser passados no action):

Código	Retorno
1	Eventos
2	Contatos
3	Marcadores e Feeds
4	Mensagens
5	Amigos (tanto para os aceitos e não aceitos)
6	Notas

Tabela 4: Código dos actions e seus retornos

4. Incluindo um Novo Registro

Para incluir registros deve-se usar a página indados.php, na sua URL também são passados os parâmetros de usuário, senha, action e os valores que serão incluídos.

No seguinte exemplo é exibido como é criada uma nova nota:

https://www.worldorg.net/api/indados.php?user=teste&pwd=teste&action=4titulo=nova+nota&nota=texto

No quadro abaixo estão listados o que é retornado pelo deldados (esses códigos devem ser passados no action):

Código	Retorno
1	Eventos
2	Contatos
3	Marcadores e Feeds
4	Notas
5	Amigo

Tabela 5: Código dos actions e seus retornos

Existem campos que não podem ser deixados em brancos, a partir de agora serão mostrado o parâmetro de cada campo e se ele é obrigatório. Se um dos campos obrigatório estiver em branco é retornado o XML com a mensagem: EMPTY.

4.1 Campos de Eventos

Nome do Parâmetro	Descrição	Obrigatório
titulo	Título do evento	X
descricao	Descrição do evento	X
prioridade	Prioridade do evento (A=Alta, B=Baixa, M=Média)
situacao	Situação (R=Completa, N=Não Completa)
data	Data, no formato (DD/MM/YYYY)
hora	Hora, no formato (HH:MM:SS)
publico	Se o evento é público para os amigos (A=compartilhado com os amigos, N=Não)

4.2 Campos de Contato

Nome do Parâmetro	Descrição	Obrigatório
nome	Nome do contato	X
telefone	Telefone
celular	Número do celular
email	E-mail
site	Site do contato
msn	MSN do contato
yahoo	Yahoo messenger do contato
gtalk	Jabber/GTalk do contato
skype	Skype do contato
aim	AIM do contato
icq	ICQ do contato
informacoes	Informações do contato
cidade	Cidade
estado	Estado do contato
codpostal	Código postal (CEP)

4.3 Campos de Feeds e Marcadores

Nome do Parâmetro	Descrição	Obrigatório
nome	Nome do site	X
descricao	Descrição do site
url	URL do Feed/Marcadores	X
tipo	Se é um site ou um marcador (F para Feeds e S para Marcadores/Sites)	X
publico	Se é público para os amigos