Yeah, I’ve only looked on here twice. Come here to post an issue we are
having and happened to see your name pop up!
Thinking about it a little more I think it would probably be pretty simple
actually:
1. Authenticate via. OAuth somehow (would be nice to have just a simple
API key here to be honest for scenarios such as yours). Agree it can be a
bit of a headache, a lot of concepts to know about and infrastructure to
create for what could be just Basic authentication with an API key over
SSL… nevermind
2. On invoice option being selected create a new contact in FreeAgent
with name and email address, plus anything else you could fill in that
makes sense. You would want to try and find an existing contact first
3. Using the contact from step 2 create your invoice. This creates a
‘draft’ invoice (see FreeAgent Developer Dashboard).
4. Make one more call which sends out the invoice.(POST https:
//api.freeagent.com/v2/invoices/:id/send_email). It may work by making a
call to ‘mark as sent’, but it is not totally obvious if that actually
sends out email, or just marks it as it has? The call for that is PUT https://api.freeagent.com/v2/invoices/:id/transitions/mark_as_sent
Again, some confusion about how these calls exactly work, but should not be
too much trial and error. A good amount of work is really required from
FreeAgent on their docs.
We have done quite a bit with the API, we have data import scenarios so
loading all contacts, projects and tasks and matching them up on our end,
and also invoice creation and status checker. May look at timeslip syncing
from Timestamp to FreeAgent at some point so sure to find some more little
niggles. Overall though a pretty decent API.
On the note of automating a conversion funnel have a look at Zapier. They
integrate with a lot of services, including FreeAgent
(FreeAgent Integrations | Connect Your Apps with Zapier) so could help you automate some
parts of your workflow without custom code being written.
Thanks,
AdamOn Wednesday, 14 May 2014 15:19:34 UTC+1, Nathan Hornby wrote:
Hi Adam, small world!
The workflow is as follows (although admittedly isn’t really a requirement
anymore, so it has become an academic discussion):
- Potential client selects services on a front-end form and checks-out
- We ask the client if they wish to pay now via card, or later via invoice.
- Assuming the user chooses the invoice option we then speak to our
Freeagent account to create a new customer and generate an itemised invoice
based on their selections.
- The invoice gets sent to the client (the standard Freeagent method of
doing this would be fine, but naturally more control is always nice).
It’s basically an automation of our standard conversion funnel (the idea
was to use it on a streamlined service that we’re likely abandoning now).
It seems like what we’re after might be possible, you’ve certainly done
the rounds with their API! We hit a wall quite quickly as we couldn’t see a
way to generate an invoice from scratch.
oAuth always gives me a headache to be honest - we’ve used it a handful of
times and it’s always baffling. I’m sure it’s very important and all that,
but man do I miss simple API feeds - of course in this case I understand it
to be pretty justified 
Cheers,
Nathan
On 14 May 2014 15:10, Adam Barclay <barcla...@gmail.com <javascript:>>wrote:
Nathan,
What is the actual workflow here? Who owns the FreeAgent account?
Is it your FreeAgent account (or a client’s for whom you are creating an
application for)? Are you then generating an invoice for an external
customer? Say a customer purchases something from your website, you wish to
generate an invoice you use for internal purposes and then give the PDF
version of that to the client?
As for some prerequisites:
-
Yes you need to authenticate against the API first. Exactly how you
do this depends on your programming language and library. It basically
involves hitting one URL to approve an app for the first time, and then
getting an access token, and then refreshing that token before it runs out
using another URL (e.g. hit Log in to your FreeAgent account to
go through approval process, and then
https://api.freeagent.com/v2/token_endpoint to get access tokens. This
is detailed @ FreeAgent Developer Dashboard. But basically the
auth step should be a one-time process done as an admin task, then your
code deals with the access tokens and refreshing just before hitting the
API to create invoices.
-
Yes you need a client. You could for example go and create a client
‘Automated Frontend’ manually and then store the URL in a configuration
file for when you create an invoice. Or create a client before creating an
invoice, not sure what makes sense for you.
-
Dates are ISO 8601 I believe (see
ISO 8601 - Wikipedia). Should be no problem formatting
these with whatever language you are using.
-
Money is in pounds (so 1.5 for £1.50). Obviously a little dependant on
currency.
I think you may have more of a problem getting the PDF though, as I do
not believe there is an API call. It is possible to figure out the URL you
can grab the PDF from, from returned Url of invoice we remove prefix of (
https://api.freeagent.com/v2/invoices/) and replace with web version
(https://{subdomain}.freeagent.com/invoices/{invoiceId}http://freeagent.com/invoices/{invoiceId}).
From there I believe appending .pdf gets you the PDF. The problem is the
code would not be authenticated to access this URL as it’s not part of the
API. Perhaps FreeAgent devs here could point you at something that would
work?
But on a whole I agree that the documentation is not particularly clear,
and at times misses important information such as defaults, formats
required, or even all of the options in a list (such as company type)
We have invoice integration from Timestamp and have worked with them
quite a bit, but the API has been a little trial and error at times 
Hope some of this helps!
Thanks,
Adam
Red Sequence
On Tuesday, 13 May 2014 12:12:04 UTC+1, Nathan Hornby wrote:
Hi Vipul, I had quite an information rich question, I’m afraid none of
that helps with it. I am aware of the docs, that’s how I know they’re
sparse Thanks anyway!
On 13 May 2014 12:07, vipul Kumar dashin...@gmail.com wrote:
Hi Nathan,
I am also using free agent Api, and its quite intresting
FreeAgent Developer Dashboard
Try this link for documentation, and
GitHub - adoy/PHP-OAuth2: Light PHP wrapper for the OAuth 2.0 protocol (based on OAuth 2.0 Authorization Protocol draft-ietf-oauth-v2-15)
use this link for code.
U can get full hint from this url about code
Using the FreeAgent API with PHP and OAuth2 :: Outlandish
have a good day…
On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat…@3degreesagency.comwrote:
Hi all,
I’m having issues with the sparseness and lack of practical examples
in the FreeAgent API docs.
Because of the way authorisation works, am I to understand that any
API tasks performed must involve a user logging in and approving access?
This is my first stumbling block.
All I need to do is to generate an invoice at the point of sale and
allow the user to download it. But they won’t have a FreeAgent account (why
would they?) and so would have no account to ‘authorise’. Besides they
can’t authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?
Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc
- every attribute throws up a new question.
It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.
Thanks all,
Nathan
–
You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit https://groups.google.com/d/
topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com.
To post to this group, send email to freeag...@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com <javascript:>.
To post to this group, send email to freeag...@googlegroups.com<javascript:>
.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.